@jerryliang122/openclaw-qqbot 1.0.0

package/src/outbound/debounce.ts

@@ -0,0 +1,102 @@
+/**
+ * 出站消息合并防抖
+ *
+ * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸。
+ *
+ * 注：框架 ReplyDispatcher 通过 sendChain 保证 deliver 严格串行——
+ * enqueue 返回的 Promise 在文本实际发出前不会 resolve，因此上游
+ * 不会并发调用 deliver，无需 flushBeforeMedia。
+ */
+import type { DeliverDebounceConfig } from '../types.js';
+
+const DEFAULT_WINDOW_MS = 1500;
+const DEFAULT_MAX_WAIT_MS = 8000;
+const DEFAULT_SEPARATOR = '\n\n---\n\n';
+
+interface PendingDeliver {
+  texts: string[];
+  firstAt: number;
+  timer: ReturnType<typeof setTimeout> | null;
+  resolve: () => void;
+}
+
+export class DeliverDebouncer {
+  private pending = new Map<string, PendingDeliver>();
+  private readonly windowMs: number;
+  private readonly maxWaitMs: number;
+  private readonly separator: string;
+  private readonly flush: (targetId: string, mergedText: string) => Promise<void>;
+
+  constructor(
+    config: DeliverDebounceConfig | undefined,
+    flush: (targetId: string, mergedText: string) => Promise<void>,
+  ) {
+    this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    this.separator = config?.separator ?? DEFAULT_SEPARATOR;
+    this.flush = flush;
+  }
+
+  get enabled(): boolean {
+    return this.windowMs > 0;
+  }
+
+  /**
+   * 入队一条纯文本待发送消息
+   * @returns Promise，在文本实际发送时 resolve
+   */
+  async enqueue(targetId: string, text: string): Promise<void> {
+    if (!this.enabled) {
+      await this.flush(targetId, text);
+      return;
+    }
+
+    const existing = this.pending.get(targetId);
+    if (existing) {
+      existing.texts.push(text);
+      // 重置窗口定时器
+      if (existing.timer) clearTimeout(existing.timer);
+      // 检查是否超过最大等待
+      if (Date.now() - existing.firstAt >= this.maxWaitMs) {
+        await this.doFlush(targetId);
+      } else {
+        existing.timer = setTimeout(() => this.doFlush(targetId), this.windowMs);
+      }
+      return;
+    }
+
+    // 新建 pending
+    return new Promise<void>((resolve) => {
+      const pending: PendingDeliver = {
+        texts: [text],
+        firstAt: Date.now(),
+        timer: setTimeout(() => this.doFlush(targetId), this.windowMs),
+        resolve,
+      };
+      this.pending.set(targetId, pending);
+    });
+  }
+
+  private async doFlush(targetId: string): Promise<void> {
+    const pending = this.pending.get(targetId);
+    if (!pending) return;
+    this.pending.delete(targetId);
+
+    if (pending.timer) clearTimeout(pending.timer);
+    const merged = pending.texts.join(this.separator);
+
+    try {
+      await this.flush(targetId, merged);
+    } finally {
+      pending.resolve();
+    }
+  }
+
+  /**
+   * 强制刷新所有 pending
+   */
+  async flushAll(): Promise<void> {
+    const keys = [...this.pending.keys()];
+    await Promise.all(keys.map((k) => this.doFlush(k)));
+  }
+}

package/src/outbound/deliver-pipeline.ts

@@ -0,0 +1,235 @@
+/**
+ * 出站 Deliver Pipeline — 处理 AI 回复的富媒体分发
+ *
+ * 框架通过 ReplyPayload 结构化字段投递回复：
+ *   - text:         纯文本
+ *   - mediaUrl:     单个媒体 URL
+ *   - mediaUrls:    多个媒体 URL
+ *   - audioAsVoice: 语音气泡（TTS）
+ *
+ * Pipeline 按顺序处理：
+ *   1. 语音意图 — audioAsVoice (TTS → SILK → 发送)
+ *   2. 媒体发送 — mediaUrl / mediaUrls（图片/文件/视频）
+ *   3. 纯文本回复 — 走 debounce 合并
+ */
+import { sendMedia } from './media-send.js';
+import type { MediaKind, SendResult } from './outbound-service.js';
+import type { DeliverDebouncer } from './debounce.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { isPathInAllowedRoots } from './local-file-router.js';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+// ── 类型 ──
+
+export interface DeliverPayload {
+  text?: string;
+  mediaUrl?: string;
+  mediaUrls?: string[];
+  audioAsVoice?: boolean;
+}
+
+export interface DeliverInfo {
+  kind: string;
+}
+
+export interface DeliverContext {
+  qualifiedTarget: string;
+  accountId: string;
+  replyToId: string;
+  /** 会话类型（用于判断语音是否可用） */
+  chatScope?: 'direct' | 'group';
+  /** 发送文本 */
+  sendText: (to: string, text: string) => Promise<SendResult>;
+  /** 发送媒体 */
+  sendMedia: (to: string, source: string, opts?: { text?: string; mediaKind?: MediaKind }) => Promise<SendResult>;
+  /** TTS 文字转语音（返回本地音频路径，失败返回 null） */
+  textToSpeech?: (params: { text: string; cfg?: unknown; channel?: string; accountId?: string }) => Promise<{ audioPath: string | null; error?: string }>;
+  /** 音频文件转 SILK Base64（QQ 语音格式） */
+  audioFileToSilkBase64?: (audioPath: string) => Promise<string | null>;
+  /** 出站文本合并防抖（可选，启用时纯文本走 debounce） */
+  debouncer?: DeliverDebouncer;
+  /** 运行时配置 */
+  cfg?: unknown;
+  /** 日志 */
+  log?: PluginLogger;
+  /** Agent ID（用于解析相对文件路径的工作区） */
+  agentId?: string;
+}
+
+/**
+ * 解析 ReplyPayload 中的媒体 URL 列表（优先 mediaUrls，fallback 单个 mediaUrl）
+ */
+function resolveMediaUrls(payload: DeliverPayload): string[] {
+  if (payload.mediaUrls?.length) {
+    return payload.mediaUrls.filter(Boolean);
+  }
+  if (payload.mediaUrl) {
+    return [payload.mediaUrl];
+  }
+  // attachments[].path → 本地文件路径（findLocalPath() 展开可能相对路径）
+  return resolveAttachmentPaths(payload);
+}
+
+function resolveAttachmentPaths(payload: DeliverPayload): string[] {
+  const attachments = (payload as any).attachments as Array<{ path?: string; url?: string }> | undefined;
+  if (!attachments?.length) return [];
+  return attachments
+    .map((a) => a.url ?? a.path)
+    .filter((p): p is string => typeof p === 'string' && p.length > 0);
+}
+
+/**
+ * 出站 Deliver Pipeline
+ *
+ * 按顺序处理：
+ * 1. 语音意图 → TTS
+ * 2. 媒体发送 → mediaUrl / mediaUrls
+ * 3. 纯文本回复 → debounce 合并
+ */
+export async function deliverReply(
+  payload: DeliverPayload,
+  _info: DeliverInfo | undefined,
+  ctx: DeliverContext,
+): Promise<void> {
+  const text = payload.text?.trim() ?? '';
+  const mediaUrls = resolveMediaUrls(payload);
+  const hasMedia = mediaUrls.length > 0;
+
+  ctx.log?.debug(`[text] textLen=${text.length} mediaCount=${mediaUrls.length}`);
+
+  // ── Layer 1: 语音意图 ──
+  if (payload.audioAsVoice) {
+    if (ctx.textToSpeech && text) {
+      const handled = await handleVoiceIntent(text, ctx);
+      if (handled) {
+        return; // 语音已发送，不再重复发送媒体或文本
+      }
+    }
+    // TTS 不可用或合成失败 → 降级为纯文本 + 媒体
+  }
+
+  // ── Layer 2: 媒体发送 ──
+  if (hasMedia) {
+    await sendMediaUrls(ctx, mediaUrls);
+    // 附带文本一并发送
+    if (text) {
+      const result = await ctx.sendText(ctx.qualifiedTarget, text);
+      if (result.error) {
+        ctx.log?.error(`[media] sendText failed: ${result.error}`);
+      }
+    }
+    return;
+  }
+
+  // ── Layer 3: 纯文本回复 ──
+  if (!text) return;
+
+  if (ctx.debouncer) {
+    await ctx.debouncer.enqueue(ctx.qualifiedTarget, text);
+  } else {
+    const result = await ctx.sendText(ctx.qualifiedTarget, text);
+    if (result.error) {
+      ctx.log?.error(`[text] sendText failed: ${result.error}`);
+    }
+  }
+}
+
+// ── 媒体批量发送 ──
+
+async function sendMediaUrls(ctx: DeliverContext, urls: string[]): Promise<void> {
+  const failedUrls: string[] = [];
+  for (const url of urls) {
+    const result = await sendMedia({
+      to: ctx.qualifiedTarget,
+      source: url,
+      replyToId: ctx.replyToId,
+      accountId: ctx.accountId,
+      log: ctx.log,
+      agentId: ctx.agentId,
+    });
+    if (result.error) {
+      ctx.log?.error(`[media] ${result.error}`);
+      failedUrls.push(url);
+    }
+  }
+
+  // 媒体发送失败时通知用户
+  if (failedUrls.length > 0) {
+    const count = failedUrls.length;
+    const total = urls.length;
+    const failMsg = count === total
+      ? `⚠️ 媒体发送失败（${count} 个），请重试`
+      : `⚠️ ${count}/${total} 个媒体发送失败`;
+    const textResult = await ctx.sendText(ctx.qualifiedTarget, failMsg);
+    if (textResult.error) {
+      ctx.log?.error(`[media] failed to send failure notification: ${textResult.error}`);
+    }
+  }
+}
+
+// ── 语音意图处理 ──
+
+async function handleVoiceIntent(text: string, ctx: DeliverContext): Promise<boolean> {
+  if (!text || !ctx.textToSpeech) return false;
+
+  // 仅 c2c/group 支持语音消息；其他场景 fallback 发文本
+  if (ctx.chatScope && ctx.chatScope !== 'direct' && ctx.chatScope !== 'group') {
+    return false;
+  }
+
+  try {
+    const ttsResult = await ctx.textToSpeech({
+      text,
+      cfg: ctx.cfg,
+      channel: 'qqbot',
+      accountId: ctx.accountId,
+    });
+
+    if (!ttsResult.audioPath) {
+      ctx.log?.error(`[tts] TTS failed: ${ttsResult.error ?? 'no audio path returned'}`);
+      return false;
+    }
+
+    // TTS 路径安全校验：确保音频文件在允许的临时目录内
+    if (!isTtsPathSafe(ttsResult.audioPath)) {
+      ctx.log?.error(`[tts] TTS audio path blocked: ${ttsResult.audioPath}`);
+      return false;
+    }
+
+    // 优先走 SILK base64
+    if (ctx.audioFileToSilkBase64) {
+      const silkBase64 = await ctx.audioFileToSilkBase64(ttsResult.audioPath);
+      if (silkBase64) {
+        const result = await ctx.sendMedia(ctx.qualifiedTarget, silkBase64, { mediaKind: 'voice' });
+        if (result.error) ctx.log?.error(`[tts] sendVoice(base64) failed: ${result.error}`);
+        return !result.error;
+      }
+      ctx.log?.error(`[tts] SILK conversion failed, trying localPath fallback`);
+    }
+
+    // Fallback: 直接发本地路径（SDK 内部处理格式转换）
+    const result = await ctx.sendMedia(ctx.qualifiedTarget, ttsResult.audioPath, { mediaKind: 'voice' });
+    if (result.error) {
+      ctx.log?.error(`[tts] sendVoice(localPath) failed: ${result.error}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    ctx.log?.error(`[tts] TTS/voice send failed: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
+// ── TTS 路径安全 ──
+
+const TTS_ALLOWED_ROOTS = [
+  path.join(os.homedir(), '.openclaw'),
+  os.tmpdir(),
+  '/tmp',
+];
+
+function isTtsPathSafe(audioPath: string): boolean {
+  if (!path.isAbsolute(audioPath)) return false;
+  return isPathInAllowedRoots(audioPath, TTS_ALLOWED_ROOTS);
+}

package/src/outbound/index.ts

@@ -0,0 +1,3 @@
+export { OutboundService, sendText, sendMedia, sendVoice, sendVideo } from './outbound-service.js';
+export { parseTarget, normalizeTarget, isQQBotTarget } from './target.js';
+export type { SendResult, MediaKind } from './outbound-service.js';

package/src/outbound/local-file-router.ts

@@ -0,0 +1,145 @@
+/**
+ * 本地文件路由 — 检测路径并按类型自动选择发送方式
+ *
+ * 本地文件路径检测 + 文件类型推断。
+ */
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import type { MediaKind } from './outbound-service.js';
+
+/**
+ * 规范化本地路径
+ * - 剥离 file:// 前缀
+ * - 展开 ~ 为 home 目录
+ * - URL decode
+ */
+export function normalizePath(p: string): string {
+  let result = p;
+  if (result.startsWith('file://')) {
+    result = result.slice('file://'.length);
+    // Windows: file:///C:/path → C:/path
+    if (/^\/[a-zA-Z]:[\\/]/.test(result)) {
+      result = result.slice(1);
+    }
+  }
+  // URL decode
+  try {
+    result = decodeURIComponent(result);
+  } catch {
+    // keep raw if decode fails
+  }
+  // ~ 展开
+  if (result === '~' || result.startsWith('~/') || result.startsWith('~\\')) {
+    result = result.replace(/^~/, os.homedir());
+  }
+  return result;
+}
+
+/**
+ * 判断一个 source 是否为本地文件路径
+ */
+export function isLocalFilePath(source: string): boolean {
+  if (!source) return false;
+  if (source.startsWith('http://') || source.startsWith('https://')) return false;
+  if (source.startsWith('data:')) return false;
+  if (source.startsWith('file://')) return true;
+  if (source === '~' || source.startsWith('~/') || source.startsWith('~\\')) return true;
+  if (source.startsWith('/')) return true;
+  if (/^[a-zA-Z]:[\\/]/.test(source)) return true;
+  if (source.startsWith('\\\\')) return true;
+  if (source.startsWith('./') || source.startsWith('../')) return true;
+  if (source.startsWith('.\\') || source.startsWith('..\\')) return true;
+  return false;
+}
+
+/**
+ * 判断一个 source 是否为 Base64 data URL
+ */
+export function isDataUrl(source: string): boolean {
+  return source.startsWith('data:');
+}
+
+/**
+ * 验证本地文件存在且可读
+ */
+export function validateLocalFile(filePath: string): boolean {
+  try {
+    fs.accessSync(filePath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 获取本地文件大小（字节），不存在返回 -1
+ */
+export function getFileSize(filePath: string): number {
+  try {
+    return fs.statSync(filePath).size;
+  } catch {
+    return -1;
+  }
+}
+
+// ── 扩展名 → MediaKind 映射 ──
+
+const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp', '.svg', '.ico']);
+const VOICE_EXTS = new Set(['.wav', '.mp3', '.silk', '.amr', '.ogg', '.flac', '.aac', '.m4a']);
+const VIDEO_EXTS = new Set(['.mp4', '.avi', '.mov', '.mkv', '.webm', '.flv', '.wmv']);
+
+/**
+ * 根据文件扩展名推断 MediaKind
+ */
+export function inferMediaKind(filePath: string): MediaKind {
+  const ext = path.extname(filePath).toLowerCase();
+  if (IMAGE_EXTS.has(ext)) return 'image';
+  if (VOICE_EXTS.has(ext)) return 'voice';
+  if (VIDEO_EXTS.has(ext)) return 'video';
+  return 'file';
+}
+
+/**
+ * 根据 MIME type 推断 MediaKind
+ */
+export function inferMediaKindFromMime(mime: string): MediaKind {
+  const lower = mime.toLowerCase();
+  if (lower.startsWith('image/')) return 'image';
+  if (lower.startsWith('audio/') || lower === 'voice') return 'voice';
+  if (lower.startsWith('video/')) return 'video';
+  return 'file';
+}
+
+/**
+ * 从 data URL 提取 MIME type
+ */
+export function extractMimeFromDataUrl(dataUrl: string): string | undefined {
+  const match = dataUrl.match(/^data:([^;,]+)/);
+  return match?.[1];
+}
+
+// ── 路径安全校验 ──
+
+/**
+ * 校验本地文件真实路径是否在允许的目录列表中。
+ * 同时解析符号链接和规范化路径，防止路径穿越。
+ *
+ * @returns true 表示路径在允许的目录内
+ */
+export function isPathInAllowedRoots(absPath: string, allowedRoots: string[]): boolean {
+  if (!allowedRoots.length) return false;
+  try {
+    const real = fs.realpathSync(absPath);
+    return allowedRoots.some((root) => {
+      try {
+        const rootReal = fs.existsSync(root) ? fs.realpathSync(root) : root;
+        return real.startsWith(rootReal + path.sep) || real === rootReal;
+      } catch {
+        return false;
+      }
+    });
+  } catch {
+    return false;
+  }
+}