@ryantest/openclaw-qqbot 0.0.1

package/src/inbound-attachments.ts

@@ -0,0 +1,304 @@
+/**
+ * 入站附件处理模块
+ *
+ * 负责下载、转换、转录用户发送的附件（图片/语音/文件），
+ * 并归类为统一的 ProcessedAttachments 结构供 gateway 消费。
+ */
+
+import { downloadFile } from "./image-server.js";
+import { convertSilkToWav, isVoiceAttachment, formatDuration } from "./utils/audio-convert.js";
+import { transcribeAudio, resolveSTTConfig } from "./stt.js";
+import { getQQBotMediaDir } from "./utils/platform.js";
+
+// ============ 类型定义 ============
+
+export interface RawAttachment {
+  content_type: string;
+  url: string;
+  filename?: string;
+  voice_wav_url?: string;
+  asr_refer_text?: string;
+}
+
+export type TranscriptSource = "stt" | "asr" | "fallback";
+
+/** processAttachments 的返回值 */
+export interface ProcessedAttachments {
+  /** 附件描述文本（其它类型附件） */
+  attachmentInfo: string;
+  /** 图片本地路径或远程 URL */
+  imageUrls: string[];
+  /** 图片 MIME 类型（与 imageUrls 一一对应） */
+  imageMediaTypes: string[];
+  /** 语音本地路径 */
+  voiceAttachmentPaths: string[];
+  /** 语音远程 URL */
+  voiceAttachmentUrls: string[];
+  /** QQ ASR 原始识别文本 */
+  voiceAsrReferTexts: string[];
+  /** 语音转录文本 */
+  voiceTranscripts: string[];
+  /** 转录来源 */
+  voiceTranscriptSources: TranscriptSource[];
+  /** 每个附件的本地路径（与原始 attachments 数组一一对应，未下载的为 null） */
+  attachmentLocalPaths: Array<string | null>;
+}
+
+interface ProcessContext {
+  accountId: string;
+  cfg: unknown;
+  log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+  };
+}
+
+// ============ 空结果常量 ============
+
+const EMPTY_RESULT: ProcessedAttachments = {
+  attachmentInfo: "",
+  imageUrls: [],
+  imageMediaTypes: [],
+  voiceAttachmentPaths: [],
+  voiceAttachmentUrls: [],
+  voiceAsrReferTexts: [],
+  voiceTranscripts: [],
+  voiceTranscriptSources: [],
+  attachmentLocalPaths: [],
+};
+
+// ============ 主函数 ============
+
+/**
+ * 处理入站消息的附件列表。
+ *
+ * 三阶段流水线：
+ * 1. 并行下载所有附件到本地
+ * 2. 并行处理语音转换 + STT 转录
+ * 3. 按原始顺序归类结果
+ */
+export async function processAttachments(
+  attachments: RawAttachment[] | undefined,
+  ctx: ProcessContext,
+): Promise<ProcessedAttachments> {
+  if (!attachments?.length) return EMPTY_RESULT;
+
+  const { accountId, cfg, log } = ctx;
+  const downloadDir = getQQBotMediaDir("downloads");
+  const prefix = `[qqbot:${accountId}]`;
+
+  // 结果收集
+  const imageUrls: string[] = [];
+  const imageMediaTypes: string[] = [];
+  const voiceAttachmentPaths: string[] = [];
+  const voiceAttachmentUrls: string[] = [];
+  const voiceAsrReferTexts: string[] = [];
+  const voiceTranscripts: string[] = [];
+  const voiceTranscriptSources: TranscriptSource[] = [];
+  const attachmentLocalPaths: Array<string | null> = [];
+  const otherAttachments: string[] = [];
+
+  // Phase 1: 并行下载所有附件
+  const downloadTasks = attachments.map(async (att) => {
+    const attUrl = att.url?.startsWith("//") ? `https:${att.url}` : att.url;
+    const isVoice = isVoiceAttachment(att);
+    const wavUrl = isVoice && att.voice_wav_url
+      ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+      : "";
+
+    let localPath: string | null = null;
+    let audioPath: string | null = null;
+
+    if (isVoice && wavUrl) {
+      const wavLocalPath = await downloadFile(wavUrl, downloadDir);
+      if (wavLocalPath) {
+        localPath = wavLocalPath;
+        audioPath = wavLocalPath;
+        log?.info(`${prefix} Voice attachment: ${att.filename}, downloaded WAV directly (skip SILK→WAV)`);
+      } else {
+        log?.error(`${prefix} Failed to download voice_wav_url, falling back to original URL`);
+      }
+    }
+
+    if (!localPath) {
+      localPath = await downloadFile(attUrl, downloadDir, att.filename);
+    }
+
+    return { att, attUrl, isVoice, localPath, audioPath };
+  });
+
+  const downloadResults = await Promise.all(downloadTasks);
+
+  // Phase 2: 并行处理语音转换 + 转录（非语音附件同步归类）
+  const processTasks = downloadResults.map(async ({ att, attUrl, isVoice, localPath, audioPath }) => {
+    const asrReferText = typeof att.asr_refer_text === "string" ? att.asr_refer_text.trim() : "";
+    const wavUrl = isVoice && att.voice_wav_url
+      ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+      : "";
+    const voiceSourceUrl = wavUrl || attUrl;
+
+    const meta = {
+      voiceUrl: isVoice && voiceSourceUrl ? voiceSourceUrl : undefined,
+      asrReferText: isVoice && asrReferText ? asrReferText : undefined,
+    };
+
+    if (localPath) {
+      if (att.content_type?.startsWith("image/")) {
+        log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+        return { localPath, type: "image" as const, contentType: att.content_type, meta };
+      } else if (isVoice) {
+        log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+        return processVoiceAttachment(localPath, audioPath, att, asrReferText, cfg, downloadDir, log, prefix);
+      } else {
+        log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+        return { localPath, type: "other" as const, filename: att.filename, meta };
+      }
+    } else {
+      log?.error(`${prefix} Failed to download: ${attUrl}`);
+      if (att.content_type?.startsWith("image/")) {
+        return { localPath: null, type: "image-fallback" as const, attUrl, contentType: att.content_type, meta };
+      } else if (isVoice && asrReferText) {
+        log?.info(`${prefix} Voice attachment download failed, using asr_refer_text fallback`);
+        return { localPath: null, type: "voice-fallback" as const, transcript: asrReferText, meta };
+      } else {
+        return { localPath: null, type: "other-fallback" as const, filename: att.filename ?? att.content_type, meta };
+      }
+    }
+  });
+
+  const processResults = await Promise.all(processTasks);
+
+  // Phase 3: 按原始顺序归类结果
+  for (const result of processResults) {
+    if (result.meta.voiceUrl) voiceAttachmentUrls.push(result.meta.voiceUrl);
+    if (result.meta.asrReferText) voiceAsrReferTexts.push(result.meta.asrReferText);
+
+    if (result.type === "image" && result.localPath) {
+      imageUrls.push(result.localPath);
+      imageMediaTypes.push(result.contentType);
+      attachmentLocalPaths.push(result.localPath);
+    } else if (result.type === "voice" && result.localPath) {
+      voiceAttachmentPaths.push(result.localPath);
+      voiceTranscripts.push(result.transcript);
+      voiceTranscriptSources.push(result.transcriptSource);
+      attachmentLocalPaths.push(result.localPath);
+    } else if (result.type === "other" && result.localPath) {
+      otherAttachments.push(`[附件: ${result.localPath}]`);
+      attachmentLocalPaths.push(result.localPath);
+    } else if (result.type === "image-fallback") {
+      imageUrls.push(result.attUrl);
+      imageMediaTypes.push(result.contentType);
+      attachmentLocalPaths.push(null);
+    } else if (result.type === "voice-fallback") {
+      voiceTranscripts.push(result.transcript);
+      voiceTranscriptSources.push("asr");
+      attachmentLocalPaths.push(null);
+    } else if (result.type === "other-fallback") {
+      otherAttachments.push(`[附件: ${result.filename}] (下载失败)`);
+      attachmentLocalPaths.push(null);
+    }
+  }
+
+  const attachmentInfo = otherAttachments.length > 0 ? "\n" + otherAttachments.join("\n") : "";
+
+  return {
+    attachmentInfo,
+    imageUrls,
+    imageMediaTypes,
+    voiceAttachmentPaths,
+    voiceAttachmentUrls,
+    voiceAsrReferTexts,
+    voiceTranscripts,
+    voiceTranscriptSources,
+    attachmentLocalPaths,
+  };
+}
+
+/**
+ * 将语音转录结果组装为用户消息中的文本片段。
+ */
+export function formatVoiceText(transcripts: string[]): string {
+  if (transcripts.length === 0) return "";
+  return transcripts.length === 1
+    ? `[语音消息] ${transcripts[0]}`
+    : transcripts.map((t, i) => `[语音${i + 1}] ${t}`).join("\n");
+}
+
+// ============ 内部辅助 ============
+
+type VoiceResult =
+  | { localPath: string; type: "voice"; transcript: string; transcriptSource: TranscriptSource; meta: { voiceUrl?: string; asrReferText?: string } }
+  | { localPath: string; type: "voice"; transcript: string; transcriptSource: TranscriptSource; meta: { voiceUrl?: string; asrReferText?: string } };
+
+async function processVoiceAttachment(
+  localPath: string,
+  audioPath: string | null,
+  att: RawAttachment,
+  asrReferText: string,
+  cfg: unknown,
+  downloadDir: string,
+  log: ProcessContext["log"],
+  prefix: string,
+): Promise<VoiceResult> {
+  const wavUrl = att.voice_wav_url
+    ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+    : "";
+  const attUrl = att.url?.startsWith("//") ? `https:${att.url}` : att.url;
+  const voiceSourceUrl = wavUrl || attUrl;
+  const meta = {
+    voiceUrl: voiceSourceUrl || undefined,
+    asrReferText: asrReferText || undefined,
+  };
+
+  const sttCfg = resolveSTTConfig(cfg as Record<string, unknown>);
+  if (!sttCfg) {
+    if (asrReferText) {
+      log?.info(`${prefix} Voice attachment: ${att.filename} (STT not configured, using asr_refer_text fallback)`);
+      return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+    }
+    log?.info(`${prefix} Voice attachment: ${att.filename} (STT not configured, skipping transcription)`);
+    return { localPath, type: "voice", transcript: "[语音消息 - 语音识别未配置，无法转录]", transcriptSource: "fallback", meta };
+  }
+
+  // SILK→WAV 转换
+  if (!audioPath) {
+    log?.info(`${prefix} Voice attachment: ${att.filename}, converting SILK→WAV...`);
+    try {
+      const wavResult = await convertSilkToWav(localPath, downloadDir);
+      if (wavResult) {
+        audioPath = wavResult.wavPath;
+        log?.info(`${prefix} Voice converted: ${wavResult.wavPath} (${formatDuration(wavResult.duration)})`);
+      } else {
+        audioPath = localPath;
+      }
+    } catch (convertErr) {
+      log?.error(`${prefix} Voice conversion failed: ${convertErr}`);
+      if (asrReferText) {
+        return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+      }
+      return { localPath, type: "voice", transcript: "[语音消息 - 格式转换失败]", transcriptSource: "fallback", meta };
+    }
+  }
+
+  // STT 转录
+  try {
+    const transcript = await transcribeAudio(audioPath!, cfg as Record<string, unknown>);
+    if (transcript) {
+      log?.info(`${prefix} STT transcript: ${transcript.slice(0, 100)}...`);
+      return { localPath, type: "voice", transcript, transcriptSource: "stt", meta };
+    }
+    if (asrReferText) {
+      log?.info(`${prefix} STT returned empty result, using asr_refer_text fallback`);
+      return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+    }
+    log?.info(`${prefix} STT returned empty result`);
+    return { localPath, type: "voice", transcript: "[语音消息 - 转录结果为空]", transcriptSource: "fallback", meta };
+  } catch (sttErr) {
+    log?.error(`${prefix} STT failed: ${sttErr}`);
+    if (asrReferText) {
+      return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+    }
+    return { localPath, type: "voice", transcript: "[语音消息 - 转录失败]", transcriptSource: "fallback", meta };
+  }
+}

package/src/known-users.ts

@@ -0,0 +1,353 @@
+/**
+ * 已知用户存储
+ * 记录与机器人交互过的所有用户
+ * 支持主动消息和批量通知功能
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+// 已知用户信息接口
+export interface KnownUser {
+  /** 用户 openid（唯一标识） */
+  openid: string;
+  /** 消息类型：私聊用户 / 群组 */
+  type: "c2c" | "group";
+  /** 用户昵称（如有） */
+  nickname?: string;
+  /** 群组 openid（如果是群消息） */
+  groupOpenid?: string;
+  /** 关联的机器人账户 ID */
+  accountId: string;
+  /** 首次交互时间戳 */
+  firstSeenAt: number;
+  /** 最后交互时间戳 */
+  lastSeenAt: number;
+  /** 交互次数 */
+  interactionCount: number;
+}
+
+import { getQQBotDataDir } from "./utils/platform.js";
+
+// 存储文件路径
+const KNOWN_USERS_DIR = getQQBotDataDir("data");
+const KNOWN_USERS_FILE = path.join(KNOWN_USERS_DIR, "known-users.json");
+
+// 内存缓存
+let usersCache: Map<string, KnownUser> | null = null;
+
+// 写入节流配置
+const SAVE_THROTTLE_MS = 5000; // 5秒写入一次
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let isDirty = false;
+
+/**
+ * 确保目录存在
+ */
+function ensureDir(): void {
+  if (!fs.existsSync(KNOWN_USERS_DIR)) {
+    fs.mkdirSync(KNOWN_USERS_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 从文件加载用户数据到缓存
+ */
+function loadUsersFromFile(): Map<string, KnownUser> {
+  if (usersCache !== null) {
+    return usersCache;
+  }
+  
+  usersCache = new Map();
+  
+  try {
+    if (fs.existsSync(KNOWN_USERS_FILE)) {
+      const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
+      const users = JSON.parse(data) as KnownUser[];
+      
+      for (const user of users) {
+        // 使用复合键：accountId + type + openid（群组还要加 groupOpenid）
+        const key = makeUserKey(user);
+        usersCache.set(key, user);
+      }
+      
+      console.log(`[known-users] Loaded ${usersCache.size} users`);
+    }
+  } catch (err) {
+    console.error(`[known-users] Failed to load users: ${err}`);
+    usersCache = new Map();
+  }
+  
+  return usersCache;
+}
+
+/**
+ * 保存用户数据到文件（节流版本）
+ */
+function saveUsersToFile(): void {
+  if (!isDirty) return;
+  
+  if (saveTimer) {
+    return; // 已有定时器在等待
+  }
+  
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    doSaveUsersToFile();
+  }, SAVE_THROTTLE_MS);
+}
+
+/**
+ * 实际执行保存
+ */
+function doSaveUsersToFile(): void {
+  if (!usersCache || !isDirty) return;
+  
+  try {
+    ensureDir();
+    const users = Array.from(usersCache.values());
+    fs.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(users, null, 2), "utf-8");
+    isDirty = false;
+  } catch (err) {
+    console.error(`[known-users] Failed to save users: ${err}`);
+  }
+}
+
+/**
+ * 强制立即保存（用于进程退出前）
+ */
+export function flushKnownUsers(): void {
+  if (saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+  }
+  doSaveUsersToFile();
+}
+
+/**
+ * 生成用户唯一键
+ */
+function makeUserKey(user: Partial<KnownUser>): string {
+  const base = `${user.accountId}:${user.type}:${user.openid}`;
+  if (user.type === "group" && user.groupOpenid) {
+    return `${base}:${user.groupOpenid}`;
+  }
+  return base;
+}
+
+/**
+ * 记录已知用户（收到消息时调用）
+ * @param user 用户信息（部分字段）
+ */
+export function recordKnownUser(user: {
+  openid: string;
+  type: "c2c" | "group";
+  nickname?: string;
+  groupOpenid?: string;
+  accountId: string;
+}): void {
+  const cache = loadUsersFromFile();
+  const key = makeUserKey(user);
+  const now = Date.now();
+  
+  const existing = cache.get(key);
+  
+  if (existing) {
+    // 更新已存在的用户
+    existing.lastSeenAt = now;
+    existing.interactionCount++;
+    if (user.nickname && user.nickname !== existing.nickname) {
+      existing.nickname = user.nickname;
+    }
+  } else {
+    // 新用户
+    const newUser: KnownUser = {
+      openid: user.openid,
+      type: user.type,
+      nickname: user.nickname,
+      groupOpenid: user.groupOpenid,
+      accountId: user.accountId,
+      firstSeenAt: now,
+      lastSeenAt: now,
+      interactionCount: 1,
+    };
+    cache.set(key, newUser);
+    console.log(`[known-users] New user: ${user.openid} (${user.type})`);
+  }
+  
+  isDirty = true;
+  saveUsersToFile();
+}
+
+/**
+ * 获取单个用户信息
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function getKnownUser(
+  accountId: string,
+  openid: string,
+  type: "c2c" | "group" = "c2c",
+  groupOpenid?: string
+): KnownUser | undefined {
+  const cache = loadUsersFromFile();
+  const key = makeUserKey({ accountId, openid, type, groupOpenid });
+  return cache.get(key);
+}
+
+/**
+ * 列出所有已知用户
+ * @param options 筛选选项
+ */
+export function listKnownUsers(options?: {
+  /** 筛选特定机器人账户的用户 */
+  accountId?: string;
+  /** 筛选消息类型 */
+  type?: "c2c" | "group";
+  /** 最近活跃时间（毫秒，如 86400000 表示最近 24 小时） */
+  activeWithin?: number;
+  /** 返回数量限制 */
+  limit?: number;
+  /** 排序方式 */
+  sortBy?: "lastSeenAt" | "firstSeenAt" | "interactionCount";
+  /** 排序方向 */
+  sortOrder?: "asc" | "desc";
+}): KnownUser[] {
+  const cache = loadUsersFromFile();
+  let users = Array.from(cache.values());
+  
+  // 筛选
+  if (options?.accountId) {
+    users = users.filter(u => u.accountId === options.accountId);
+  }
+  if (options?.type) {
+    users = users.filter(u => u.type === options.type);
+  }
+  if (options?.activeWithin) {
+    const cutoff = Date.now() - options.activeWithin;
+    users = users.filter(u => u.lastSeenAt >= cutoff);
+  }
+  
+  // 排序
+  const sortBy = options?.sortBy ?? "lastSeenAt";
+  const sortOrder = options?.sortOrder ?? "desc";
+  users.sort((a, b) => {
+    const aVal = a[sortBy] ?? 0;
+    const bVal = b[sortBy] ?? 0;
+    return sortOrder === "asc" ? aVal - bVal : bVal - aVal;
+  });
+  
+  // 限制数量
+  if (options?.limit && options.limit > 0) {
+    users = users.slice(0, options.limit);
+  }
+  
+  return users;
+}
+
+/**
+ * 获取用户统计信息
+ * @param accountId 机器人账户 ID（可选，不传则返回所有账户的统计）
+ */
+export function getKnownUsersStats(accountId?: string): {
+  totalUsers: number;
+  c2cUsers: number;
+  groupUsers: number;
+  activeIn24h: number;
+  activeIn7d: number;
+} {
+  let users = listKnownUsers({ accountId });
+  
+  const now = Date.now();
+  const day = 24 * 60 * 60 * 1000;
+  
+  return {
+    totalUsers: users.length,
+    c2cUsers: users.filter(u => u.type === "c2c").length,
+    groupUsers: users.filter(u => u.type === "group").length,
+    activeIn24h: users.filter(u => now - u.lastSeenAt < day).length,
+    activeIn7d: users.filter(u => now - u.lastSeenAt < 7 * day).length,
+  };
+}
+
+/**
+ * 删除用户记录
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function removeKnownUser(
+  accountId: string,
+  openid: string,
+  type: "c2c" | "group" = "c2c",
+  groupOpenid?: string
+): boolean {
+  const cache = loadUsersFromFile();
+  const key = makeUserKey({ accountId, openid, type, groupOpenid });
+  
+  if (cache.has(key)) {
+    cache.delete(key);
+    isDirty = true;
+    saveUsersToFile();
+    console.log(`[known-users] Removed user ${openid}`);
+    return true;
+  }
+  
+  return false;
+}
+
+/**
+ * 清除所有用户记录
+ * @param accountId 机器人账户 ID（可选，不传则清除所有）
+ */
+export function clearKnownUsers(accountId?: string): number {
+  const cache = loadUsersFromFile();
+  let count = 0;
+  
+  if (accountId) {
+    // 只清除指定账户的用户
+    for (const [key, user] of cache.entries()) {
+      if (user.accountId === accountId) {
+        cache.delete(key);
+        count++;
+      }
+    }
+  } else {
+    // 清除所有
+    count = cache.size;
+    cache.clear();
+  }
+  
+  if (count > 0) {
+    isDirty = true;
+    doSaveUsersToFile(); // 立即保存
+    console.log(`[known-users] Cleared ${count} users`);
+  }
+  
+  return count;
+}
+
+/**
+ * 获取用户的所有群组（某用户在哪些群里交互过）
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ */
+export function getUserGroups(accountId: string, openid: string): string[] {
+  const users = listKnownUsers({ accountId, type: "group" });
+  return users
+    .filter(u => u.openid === openid && u.groupOpenid)
+    .map(u => u.groupOpenid!);
+}
+
+/**
+ * 获取群组的所有成员
+ * @param accountId 机器人账户 ID
+ * @param groupOpenid 群组 openid
+ */
+export function getGroupMembers(accountId: string, groupOpenid: string): KnownUser[] {
+  return listKnownUsers({ accountId, type: "group" })
+    .filter(u => u.groupOpenid === groupOpenid);
+}