@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/outbound/cron-scheduler.ts

@@ -0,0 +1,130 @@
+/**
+ * Cron 定时消息
+ *
+ * 当 AI 输出 `QQBOT_PAYLOAD: { "type": "cron_reminder", "cron": "...", "text": "..." }`
+ * 时，注册一个定时任务在指定时间向用户发送提醒消息。
+ *
+ * 使用 setTimeout 实现（适合单次/短期提醒），不依赖外部调度库。
+ * 复杂 cron 表达式场景需要用户自行接入 node-cron 等库。
+ */
+
+export interface CronReminderPayload {
+  /** 提醒文本 */
+  text: string;
+  /** 触发时间：ISO 8601 字符串 或 Unix ms 或 "in Xm/Xh/Xd" 相对格式 */
+  at?: string | number;
+  /** cron 表达式（暂不支持，仅做记录） */
+  cron?: string;
+  /** 发送目标 */
+  target?: string;
+}
+
+export interface ScheduledReminder {
+  id: string;
+  text: string;
+  target: string;
+  triggerAt: number;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+type SendFn = (target: string, text: string) => Promise<void>;
+
+/**
+ * 定时消息调度器
+ */
+export class CronScheduler {
+  private reminders = new Map<string, ScheduledReminder>();
+  private nextId = 0;
+
+  constructor(private readonly send: SendFn) {}
+
+  /**
+   * 注册一个定时提醒
+   */
+  schedule(payload: CronReminderPayload, defaultTarget: string): { id: string; triggerAt: number; confirmText: string } {
+    const id = `reminder_${++this.nextId}`;
+    const target = payload.target ?? defaultTarget;
+    const triggerAt = resolveTriggerTime(payload.at);
+    const delayMs = Math.max(0, triggerAt - Date.now());
+    const text = payload.text?.trim() ?? '定时提醒';
+
+    const reminder: ScheduledReminder = {
+      id,
+      text,
+      target,
+      triggerAt,
+    };
+
+    // 如果延迟小于 24 小时，直接 setTimeout；否则只记录不调度
+    const MAX_TIMEOUT = 24 * 60 * 60 * 1000; // 24h
+    if (delayMs <= MAX_TIMEOUT) {
+      reminder.timer = setTimeout(async () => {
+        this.reminders.delete(id);
+        try {
+          await this.send(target, `⏰ ${text}`);
+        } catch { /* swallow */ }
+      }, delayMs);
+    }
+
+    this.reminders.set(id, reminder);
+
+    const when = new Date(triggerAt);
+    const confirmText = `✅ Reminder scheduled for ${when.toLocaleString()}: "${text}"`;
+    return { id, triggerAt, confirmText };
+  }
+
+  /**
+   * 取消一个提醒
+   */
+  cancel(id: string): boolean {
+    const reminder = this.reminders.get(id);
+    if (!reminder) return false;
+    if (reminder.timer) clearTimeout(reminder.timer);
+    this.reminders.delete(id);
+    return true;
+  }
+
+  /**
+   * 清除所有提醒
+   */
+  clear(): void {
+    for (const [, r] of this.reminders) {
+      if (r.timer) clearTimeout(r.timer);
+    }
+    this.reminders.clear();
+  }
+
+  /**
+   * 获取所有待触发的提醒
+   */
+  listPending(): ScheduledReminder[] {
+    return [...this.reminders.values()];
+  }
+}
+
+// ── 时间解析 ──
+
+function resolveTriggerTime(at: string | number | undefined): number {
+  if (!at) return Date.now() + 60_000; // 默认 1 分钟后
+
+  if (typeof at === 'number') return at;
+
+  // ISO 8601
+  const dateMs = new Date(at).getTime();
+  if (!Number.isNaN(dateMs)) return dateMs;
+
+  // 相对格式: "in 5m", "in 2h", "in 1d"
+  const relMatch = at.match(/^(?:in\s+)?(\d+)\s*(m|min|h|hour|d|day|s|sec)/i);
+  if (relMatch) {
+    const val = Number(relMatch[1]);
+    const unit = relMatch[2].toLowerCase();
+    const multiplier =
+      unit.startsWith('s') ? 1000 :
+      unit.startsWith('m') ? 60_000 :
+      unit.startsWith('h') ? 3600_000 :
+      unit.startsWith('d') ? 86400_000 : 60_000;
+    return Date.now() + val * multiplier;
+  }
+
+  return Date.now() + 60_000;
+}

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/image-size.ts

@@ -0,0 +1,123 @@
+/**
+ * Markdown 图片尺寸探测
+ *
+ * 发送前探测图片宽高，格式化为 `![img #WxH](url)` 格式。
+ * QQ 客户端 Markdown 渲染时需要这个尺寸提示来优化图片显示比例。
+ */
+
+import { validateRemoteUrl } from '../utils/ssrf-guard.js';
+
+/** 图片尺寸结果 */
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * 通过 HTTP Range 请求前 N 字节解析图片尺寸
+ *
+ * 支持 PNG / JPEG / GIF / WebP 格式的快速头部探测（不下载完整图片）。
+ * 内置 SSRF 防护：fetch 前先校验 URL 安全性。
+ */
+export async function getImageSize(url: string, timeoutMs = 5000): Promise<ImageSize | null> {
+  try {
+    // SSRF 防护：禁止访问内网 / 云元数据端点
+    await validateRemoteUrl(url);
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const resp = await fetch(url, {
+      signal: controller.signal,
+      headers: { Range: 'bytes=0-32767' }, // 请求前 32KB 足够解析头
+    });
+    clearTimeout(timer);
+
+    if (!resp.ok && resp.status !== 206) return null;
+
+    const buffer = Buffer.from(await resp.arrayBuffer());
+    return parseImageDimensions(buffer);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 从 buffer 头部解析图片尺寸
+ */
+function parseImageDimensions(buffer: Buffer): ImageSize | null {
+  if (buffer.length < 8) return null;
+
+  // PNG: 前 8 字节签名 + IHDR chunk (offset 16: width BE uint32, offset 20: height BE uint32)
+  if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+    if (buffer.length >= 24) {
+      return {
+        width: buffer.readUInt32BE(16),
+        height: buffer.readUInt32BE(20),
+      };
+    }
+  }
+
+  // JPEG: 搜索 SOFn marker (0xFF 0xC0-0xCF, 除 0xC4/0xC8/0xCC)
+  if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+    let offset = 2;
+    while (offset < buffer.length - 9) {
+      if (buffer[offset] !== 0xff) { offset++; continue; }
+      const marker = buffer[offset + 1];
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return {
+          height: buffer.readUInt16BE(offset + 5),
+          width: buffer.readUInt16BE(offset + 7),
+        };
+      }
+      const segLen = buffer.readUInt16BE(offset + 2);
+      offset += 2 + segLen;
+    }
+  }
+
+  // GIF: offset 6: width LE uint16, offset 8: height LE uint16
+  if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46) {
+    if (buffer.length >= 10) {
+      return {
+        width: buffer.readUInt16LE(6),
+        height: buffer.readUInt16LE(8),
+      };
+    }
+  }
+
+  // WebP: RIFF header + "WEBP" + VP8 chunks
+  if (buffer.length >= 30 && buffer.toString('ascii', 0, 4) === 'RIFF' && buffer.toString('ascii', 8, 12) === 'WEBP') {
+    const chunk = buffer.toString('ascii', 12, 16);
+    if (chunk === 'VP8 ' && buffer.length >= 30) {
+      // Lossy VP8: offset 26-27 width (LE) & offset 28-29 height (LE), masked lower 14 bits
+      return {
+        width: buffer.readUInt16LE(26) & 0x3fff,
+        height: buffer.readUInt16LE(28) & 0x3fff,
+      };
+    }
+    if (chunk === 'VP8L' && buffer.length >= 25) {
+      // Lossless VP8L: 5 bytes at offset 21, first 14 bits = width-1, next 14 bits = height-1
+      const bits = buffer.readUInt32LE(21);
+      return {
+        width: (bits & 0x3fff) + 1,
+        height: ((bits >> 14) & 0x3fff) + 1,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 格式化 QQ Markdown 图片标签（带尺寸提示）
+ *
+ * @example
+ * formatQQMarkdownImage('https://x/img.png', { width: 800, height: 600 })
+ * // → '![img #800x600](https://x/img.png)'
+ */
+export function formatQQMarkdownImage(url: string, size?: ImageSize | null): string {
+  if (size) {
+    return `![img #${size.width}x${size.height}](${url})`;
+  }
+  return `![img](${url})`;
+}

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';