@jerryliang122/openclaw-qqbot 1.0.0

package/src/heartbeat-adapter.ts

@@ -0,0 +1,57 @@
+/**
+ * QQBot Heartbeat 适配器
+ *
+ * Typing 指示器
+ */
+
+import { startTypingWithRenewal, stopTyping } from './typing-lifecycle.js';
+import { inferQQBotScope } from './features/quota-manager.js';
+import { getGateway } from './outbound/outbound-service.js';
+import { tryParseTarget } from './outbound/target.js';
+
+/**
+ * QQBot Heartbeat Adapter
+ */
+export const qqbotHeartbeatAdapter = {
+  sendTyping: async (params: {
+    cfg: any;
+    to: string;
+    accountId?: string | null;
+    threadId?: string | number | null;
+    replyToId?: string;
+  }) => {
+    const { to, accountId, replyToId } = params;
+
+    if (!accountId || !replyToId) {
+      return;
+    }
+
+    const scope = inferQQBotScope(to);
+    if (scope !== 'c2c') {
+      return;
+    }
+
+    await startTypingWithRenewal({
+      accountId,
+      to,
+      replyToId,
+      sendTyping: async ({ to, msgId }) => {
+        const gw = getGateway(accountId);
+        if (!gw) return false;
+
+        const target = tryParseTarget(to);
+        if (!target) {
+          return false;
+        }
+
+        const targetWithMsgId = msgId ? { ...target, msgId } : target;
+        try {
+          await gw.sendTyping(targetWithMsgId);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+    });
+  },
+};

package/src/message-adapter.ts

@@ -0,0 +1,40 @@
+/**
+ * QQBot Message 适配器
+ *
+ * 定义消息生命周期能力
+ */
+
+import { qqbotChannelOutbound } from './outbound-adapter.js';
+
+/**
+ * QQBot Message Adapter
+ *
+ * 能力声明：
+ * - draftPreview: false (QQBot 不支持)
+ * - previewFinalization: false
+ * - progressUpdates: true (流式支持)
+ * - finalEdit: false (QQBot 流式限制)
+ */
+export const qqbotMessageAdapter = {
+  id: 'qqbot',
+  live: {
+    capabilities: {
+      draftPreview: false,
+      previewFinalization: false,
+      progressUpdates: true,
+    },
+    finalizer: {
+      capabilities: {
+        finalEdit: false,
+        normalFallback: true,
+        previewReceipt: false,
+        retainOnAmbiguousFailure: true,
+      },
+    },
+  },
+  receive: {
+    defaultAckPolicy: 'after_agent_dispatch' as const,
+    supportedAckPolicies: ['after_receive_record', 'after_agent_dispatch'] as const,
+  },
+  outbound: qqbotChannelOutbound,
+};

package/src/messaging-adapter.ts

@@ -0,0 +1,78 @@
+/**
+ * QQBot Messaging 适配器
+ *
+ * 处理目标解析、会话路由
+ */
+
+import { normalizeTarget, isQQBotTarget, tryParseTarget } from './outbound/target.js';
+
+/**
+ * 解析会话目标
+ */
+function resolveQQBotInboundConversation(params: {
+  to?: string;
+  conversationId?: string;
+  threadId?: string | number;
+}): { conversationId: string; parentConversationId: string } | null {
+  const rawTarget = params.to || params.conversationId || '';
+  if (!rawTarget) {
+    return null;
+  }
+
+  const parsed = tryParseTarget(rawTarget);
+  if (!parsed) {
+    return null;
+  }
+
+  if (parsed.scope !== 'c2c' && parsed.scope !== 'group') {
+    return null;
+  }
+
+  // 保存完整目标字符串（包括 scope），避免后续解析时丢失 scope 信息
+  const fullTarget = `qqbot:${parsed.scope}:${parsed.targetId}`;
+
+  return {
+    conversationId: fullTarget,
+    parentConversationId: fullTarget,
+  };
+}
+
+/**
+ * 解析投递目标
+ */
+function resolveQQBotDeliveryTarget(params: {
+  conversationId: string;
+  parentConversationId?: string;
+}): { to: string } | null {
+  const targetStr = params.parentConversationId || params.conversationId;
+  if (!targetStr) {
+    return null;
+  }
+
+  const parsed = tryParseTarget(targetStr);
+  if (!parsed) {
+    return null;
+  }
+
+  if (parsed.scope !== 'c2c' && parsed.scope !== 'group') {
+    return null;
+  }
+
+  return {
+    to: `qqbot:${parsed.scope}:${parsed.targetId}`,
+  };
+}
+
+/**
+ * QQBot Messaging Adapter
+ */
+export const qqbotMessagingAdapter = {
+  targetPrefixes: ['qqbot'],
+  normalizeTarget: (target: string) => normalizeTarget(target),
+  resolveInboundConversation: resolveQQBotInboundConversation,
+  resolveDeliveryTarget: resolveQQBotDeliveryTarget,
+  targetResolver: {
+    looksLikeId: isQQBotTarget,
+    hint: 'QQ Bot 目标格式: qqbot:c2c:openid (私聊) 或 qqbot:group:groupid (群聊)',
+  },
+};

package/src/middleware/access-control.ts

@@ -0,0 +1,125 @@
+/**
+ * 动态访问控制中间件。
+ *
+ * 从 ctx.state.policy（由 policy-injector 注入）动态读取策略，支持配置热更新。
+ * 模式：disabled | open | allowlist | pairing（仅 c2c）
+ */
+import type { Middleware } from '@tencent-connect/qqbot-nodejs';
+import { getPairingApi } from '../adapter/pairing.js';
+
+
+/**
+ * 创建动态访问控制中间件。
+ *
+ * 决策优先级：
+ *   1. disabled → 拒绝
+ *   2. open → 放行
+ *   3. allowlist → allowFrom 匹配（默认模式）
+ *   4. pairing → allowFrom + pairing store，未配对发起挑战
+ */
+export function dynamicAccessControl(params: {
+  accountId: string;
+  getRuntime: () => any;
+}): Middleware {
+  const { accountId, getRuntime } = params;
+
+  return async (ctx, next) => {
+    const p = ctx.state.policy as Record<string, unknown> | undefined;
+    const isGroup = ctx.message.kind === 'group';
+    const mode: string = isGroup
+      ? (p?.groupMode as string) ?? 'open'
+      : (p?.c2cMode as string) ?? 'allowlist';
+
+    if (mode === 'disabled') {
+      ctx.log?.info?.(`[access] blocked ${isGroup ? 'group' : 'c2c'} from ${ctx.message.senderId}: policy disabled`);
+      ctx.stop('access:policy_disabled');
+      return;
+    }
+    if (mode === 'open') {
+      await next();
+      return;
+    }
+
+    // allowlist / pairing：c2c 用 allowFrom，group 用 groupAllowFrom
+    const allowList = isGroup
+      ? ((p?.groupAllowFrom as string[]) ?? [])
+      : ((p?.allowFrom as string[]) ?? []);
+    if (!allowList.length || allowList.includes('*')) {
+      await next();
+      return;
+    }
+
+    const id = isGroup
+      ? (ctx.message.groupOpenid ?? '')
+      : (ctx.message.senderId as string);
+    if (allowList.includes(id)) {
+      await next();
+      return;
+    }
+
+    // allowlist 未匹配 → pairing 模式尝试 pairing store（仅 c2c）
+    if (mode === 'pairing' && !isGroup) {
+      await checkPairingMode(ctx, next, {
+        accountId,
+        getRuntime,
+        senderId: ctx.message.senderId as string,
+      });
+      return;
+    }
+
+    // 未匹配 → 拒绝
+    const listLabel = isGroup ? 'groupAllowFrom' : 'allowFrom';
+    ctx.log?.info?.(
+      `[access] blocked ${isGroup ? 'group' : 'c2c'} from ${id}: not in ${listLabel}`,
+    );
+    ctx.stop('access:not_allowlisted');
+  };
+}
+
+/**
+ * pairing 模式：检查 pairing store + 发起配对挑战。
+ */
+async function checkPairingMode(
+  ctx: any,
+  next: () => Promise<void>,
+  opts: { accountId: string; getRuntime: () => any; senderId: string },
+): Promise<void> {
+  const api = getPairingApi();
+
+  try {
+    const storeIds = await api.readAllowFromStore({
+      channel: 'qqbot',
+      accountId: opts.accountId,
+    });
+    if (storeIds.includes(opts.senderId) || storeIds.includes('*')) {
+      await next();
+      return;
+    }
+
+    const challenge = await api.issueChallenge({
+      channel: 'qqbot',
+      id: opts.senderId,
+      accountId: opts.accountId,
+    });
+    const frameworkReply = api.buildReply({
+      code: challenge.code,
+      channel: 'qqbot',
+    });
+    const reply = [
+      frameworkReply,
+      '',
+      'QQ 管理员可直接执行：',
+      '',
+      '```',
+      `/bot-pairing approve ${challenge.code}`,
+      '```',
+    ].join('\n');
+
+    ctx.log?.info?.(`[access] pairing required for ${opts.senderId}`);
+    await ctx.bot.sendText(ctx.replyTarget, reply).catch(() => {/* ignore */});
+    ctx.stop('access:pairing_required');
+  } catch (err) {
+    ctx.log?.error?.(`[access] pairing error: ${(err as Error).message}`);
+    ctx.stop(`access:pairing_error: ${(err as Error).message}`);
+  }
+}

package/src/middleware/attachment.ts

@@ -0,0 +1,373 @@
+/**
+ * 入站附件处理中间件
+ *
+ * 处理入站消息中的语音/图片/视频附件：
+ * - 语音：下载 → SILK转WAV → STT转文字 → 写入 ctx.state.processedAttachments
+ * - 图片：提取 URL 列表
+ * - 其他：标记为附件描述
+ *
+ * 插入位置：envelopeFormatter 之前
+ */
+import * as path from 'node:path';
+import type { MiddlewareContext } from '@tencent-connect/qqbot-nodejs';
+import {
+  convertSilkToWav,
+  isVoiceAttachment,
+} from '@tencent-connect/qqbot-nodejs/protocol';
+import type { MessageAttachment } from '../types.js';
+import { transcribeAudio, resolveSTTConfig, shouldUsePlatformAsr } from '../utils/stt.js';
+import { formatVoiceText, formatDuration, type VoiceTranscript, type TranscriptSource } from '../utils/voice-text.js';
+import { downloadRemoteMedia } from '../adapter/media.js';
+import { getAdapters } from '../adapter/resolve.js';
+
+export { formatVoiceText, formatDuration };
+export type { VoiceTranscript, TranscriptSource };
+
+/** 处理后的附件结果（写入 ctx.state.processedAttachments） */
+export interface ProcessedAttachments {
+  voiceText: string;
+  imageUrls: string[];
+  otherInfo: string;
+  transcripts: VoiceTranscript[];
+  /** 下载到本地的媒体路径（图片 + 语音，供 AI 引用） */
+  localMediaPaths: string[];
+  /** 对应 localMediaPaths 的 MIME type */
+  localMediaTypes: string[];
+  /** 远端 URL 列表（下载失败时的回退） */
+  remoteMediaUrls: string[];
+  /**
+   * 结构化媒体清单（全部附件，保持原始顺序）。
+   * 供 ctx-builder 组装 core 正规媒体通道的 media facts（MediaKind: image|audio|video|document）。
+   */
+  media: InboundMediaEntry[];
+}
+
+/**
+ * 单个入站媒体条目（对齐 core MediaKind/ChannelInboundMediaInput 语义）。
+ * localPath 与 remoteUrl 二选一可能都没有（下载失败且无 URL 时）。
+ */
+export interface InboundMediaEntry {
+  kind: 'image' | 'audio' | 'video' | 'document';
+  localPath?: string;
+  remoteUrl?: string;
+  contentType?: string;
+  filename?: string;
+  /** 仅语音：STT/平台 ASR 产出真实转写文本时为 true */
+  transcribed?: boolean;
+}
+
+interface AttachmentMiddlewareOptions {
+  /** 获取 runtime */
+  getRuntime: () => any;
+}
+
+/**
+ * 附件处理中间件
+ *
+ * SDK ctx 已提供 log 和 accountId，只需传入配置获取函数。
+ */
+export function attachmentProcessor(opts: AttachmentMiddlewareOptions) {
+  return async (ctx: MiddlewareContext, next: () => Promise<void>) => {
+    const msg = ctx.message;
+    const attachments = msg.attachments as MessageAttachment[] | undefined;
+
+    if (attachments?.length) {
+      const runtime = opts.getRuntime();
+      const adapters = getAdapters(runtime);
+      const cfg = (adapters.getConfig?.() ?? {}) as Record<string, unknown>;
+      const log = ctx.log;
+      const result = await processAttachments(attachments, cfg, log);
+
+      if (result.voiceText || result.imageUrls.length > 0 || result.otherInfo || result.localMediaPaths.length > 0) {
+        ctx.state.processedAttachments = result;
+      }
+    }
+
+    await next();
+  };
+}
+
+// ── 核心处理逻辑 ──
+
+type Log = { info: (m: string) => void; error: (m: string) => void; debug?: (m: string) => void };
+
+export async function processAttachments(
+  attachments: MessageAttachment[],
+  cfg: Record<string, unknown>,
+  log?: Log,
+): Promise<ProcessedAttachments> {
+  const sttCfg = resolveSTTConfig(cfg);
+  const usePlatformAsr = shouldUsePlatformAsr(cfg);
+  const audioPolicy = resolveAudioPolicy(cfg);
+
+  const imageUrls: string[] = [];
+  const otherParts: string[] = [];
+  const transcripts: VoiceTranscript[] = [];
+  const localMediaPaths: string[] = [];
+  const localMediaTypes: string[] = [];
+  const remoteMediaUrls: string[] = [];
+  const media: InboundMediaEntry[] = [];
+
+  // 并行下载所有附件
+  const tasks = attachments.map(async (att) => {
+    const isVoice = isVoiceAttachment(att);
+    const isImage = att.content_type?.startsWith('image/');
+    const url = normalizeUrl(att.url);
+
+    if (isImage && url) {
+      const localPath = await downloadMediaFile(url, att.filename, log);
+      return { type: 'image' as const, localPath, url, contentType: att.content_type ?? 'image/png', filename: att.filename };
+    }
+
+    if (isVoice) {
+      const transcript = await processVoiceAttachment(att, sttCfg, usePlatformAsr, audioPolicy, log);
+      return { type: 'voice' as const, transcript };
+    }
+
+    // other 类型也尝试下载
+    if (url) {
+      const localPath = await downloadMediaFile(url, att.filename, log);
+      return { type: 'other' as const, localPath, url, filename: att.filename ?? att.content_type, contentType: att.content_type };
+    }
+    return { type: 'other' as const, localPath: null, url: '', filename: att.filename ?? att.content_type, contentType: att.content_type };
+  });
+
+  const results = await Promise.all(tasks);
+
+  // 按原始顺序收集结果
+  for (const result of results) {
+    if (result.type === 'image') {
+      if (result.localPath) {
+        imageUrls.push(result.localPath);
+        localMediaPaths.push(result.localPath);
+        localMediaTypes.push(result.contentType);
+      } else {
+        imageUrls.push(result.url);
+        remoteMediaUrls.push(result.url);
+      }
+      media.push({
+        kind: 'image',
+        ...(result.localPath ? { localPath: result.localPath } : { remoteUrl: result.url }),
+        contentType: result.contentType,
+        filename: result.filename,
+      });
+    } else if (result.type === 'voice') {
+      transcripts.push(result.transcript);
+      if (result.transcript.localPath) {
+        localMediaPaths.push(result.transcript.localPath);
+        localMediaTypes.push('audio/wav');
+      } else if (result.transcript.remoteUrl) {
+        remoteMediaUrls.push(result.transcript.remoteUrl);
+      }
+      media.push({
+        kind: 'audio',
+        ...(result.transcript.localPath
+          ? { localPath: result.transcript.localPath }
+          : result.transcript.remoteUrl
+            ? { remoteUrl: result.transcript.remoteUrl }
+            : {}),
+        contentType: 'audio/wav',
+        transcribed: result.transcript.source !== 'fallback',
+      });
+    } else if (result.type === 'other') {
+      if (result.localPath) {
+        otherParts.push(`[Attachment: ${result.localPath}]`);
+        localMediaPaths.push(result.localPath);
+        localMediaTypes.push('application/octet-stream');
+      } else {
+        otherParts.push(`[Attachment: ${result.filename}]`);
+      }
+      media.push({
+        kind: kindFromContentType(result.contentType),
+        ...(result.localPath ? { localPath: result.localPath } : result.url ? { remoteUrl: result.url } : {}),
+        ...(result.contentType ? { contentType: result.contentType } : {}),
+        ...(result.filename ? { filename: result.filename } : {}),
+      });
+    }
+  }
+
+  return {
+    voiceText: formatVoiceText(transcripts),
+    imageUrls,
+    otherInfo: otherParts.join('\n'),
+    transcripts,
+    localMediaPaths,
+    localMediaTypes,
+    remoteMediaUrls,
+    media,
+  };
+}
+
+/** content_type → core MediaKind（无法识别时归为 document） */
+function kindFromContentType(contentType: string | undefined): InboundMediaEntry['kind'] {
+  if (contentType?.startsWith('video/')) return 'video';
+  if (contentType?.startsWith('image/')) return 'image';
+  if (contentType?.startsWith('audio/')) return 'audio';
+  return 'document';
+}
+
+// ── 语音处理 ──
+
+async function processVoiceAttachment(
+  att: MessageAttachment,
+  sttCfg: ReturnType<typeof resolveSTTConfig>,
+  usePlatformAsr: boolean,
+  audioPolicy: AudioPolicyResolved,
+  log?: Log,
+): Promise<VoiceTranscript> {
+  // 平台转写（asr_refer_text）仅在显式 asrFallback: true 时参与；
+  // 缺省/false 时在所有场景下丢弃——包括 STT 未配置（语音落占位文本）
+  // 与 STT 失败（不当兜底），三条泄漏路径（转写成功携带 / 转写失败回退 /
+  // 下载失败回退）一并堵死。
+  const rawAsrText = att.asr_refer_text?.trim() || undefined;
+  const asrReferText = usePlatformAsr ? rawAsrText : undefined;
+  // 远端 URL 兜底：优先 wav_url，其次原始 url
+  const remoteUrl = normalizeUrl(att.voice_wav_url) || normalizeUrl(att.url) || undefined;
+
+  // STT 未配置：占位文本；显式 asrFallback: true 时退回平台转写
+  if (!sttCfg) {
+    if (!usePlatformAsr && rawAsrText) {
+      log?.info(`Voice: STT not configured; platform asr_refer_text discarded (asrFallback not enabled)`);
+    }
+    if (asrReferText) {
+      log?.debug?.(`Voice: using asr_refer_text (STT not configured, asrFallback enabled)`);
+      return { text: asrReferText, source: 'asr', asrReferText, remoteUrl };
+    }
+    return {
+      text: '[Voice message - transcription unavailable]',
+      source: 'fallback',
+      asrReferText,
+      remoteUrl,
+    };
+  }
+
+  let localPath: string | undefined;
+  let duration: number | undefined;
+
+  try {
+    const wavUrl = normalizeUrl(att.voice_wav_url);
+    if (wavUrl) {
+      const downloaded = await downloadMediaFile(wavUrl, undefined, log);
+      if (downloaded) {
+        localPath = downloaded;
+        log?.debug?.(`Voice: downloaded WAV from voice_wav_url`);
+      }
+    }
+
+    if (!localPath) {
+      const silkUrl = normalizeUrl(att.url);
+      if (silkUrl) {
+        const silkPath = await downloadMediaFile(silkUrl, att.filename, log);
+        if (silkPath) {
+          const ext = path.extname(silkPath).toLowerCase();
+          if (audioPolicy.sttDirectFormats.includes(ext)) {
+            localPath = silkPath;
+          } else {
+            const wavResult = await convertSilkToWav(silkPath);
+            if (wavResult) {
+              localPath = wavResult.wavPath;
+              duration = wavResult.duration / 1000;
+              log?.debug?.(`Voice: SILK→WAV (${formatDuration(duration)})`);
+            } else {
+              localPath = silkPath;
+            }
+          }
+        }
+      }
+    }
+  } catch (err) {
+    log?.error(`Voice download/convert failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (localPath) {
+    try {
+      const transcript = await transcribeAudio(localPath, cfg2stt(sttCfg));
+      if (transcript) {
+        log?.debug?.(`Voice STT: ${transcript.slice(0, 80)}...`);
+        return { text: transcript, source: 'stt', duration, localPath, remoteUrl, asrReferText };
+      }
+    } catch (err) {
+      log?.error(`Voice STT failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (asrReferText) {
+    return { text: asrReferText, source: 'asr', duration, localPath, remoteUrl, asrReferText };
+  }
+
+  return {
+    text: '[Voice message - transcription failed]',
+    source: 'fallback',
+    duration,
+    localPath,
+    remoteUrl,
+    asrReferText,
+  };
+}
+
+// ── 配置 ──
+
+interface AudioPolicyResolved {
+  sttDirectFormats: string[];
+  uploadDirectFormats: string[];
+  transcodeEnabled: boolean;
+}
+
+function resolveAudioPolicy(cfg: Record<string, unknown>): AudioPolicyResolved {
+  const channels = cfg.channels as Record<string, unknown> | undefined;
+  const qqbot = channels?.qqbot as Record<string, unknown> | undefined;
+  const policy = qqbot?.audioFormatPolicy as Record<string, unknown> | undefined;
+
+  return {
+    sttDirectFormats: normalizeFormats((policy?.sttDirectFormats as string[]) ?? []),
+    uploadDirectFormats: normalizeFormats(
+      (policy?.uploadDirectFormats as string[]) ?? ['.wav', '.mp3', '.silk'],
+    ),
+    transcodeEnabled: (policy?.transcodeEnabled as boolean) !== false,
+  };
+}
+
+function normalizeFormats(formats: string[]): string[] {
+  return formats.map((f) => {
+    const lower = f.toLowerCase().trim();
+    return lower.startsWith('.') ? lower : `.${lower}`;
+  });
+}
+
+function cfg2stt(sttCfg: NonNullable<ReturnType<typeof resolveSTTConfig>>): Record<string, unknown> {
+  return { channels: { qqbot: { stt: sttCfg } } };
+}
+
+// ── 文件工具 ──
+
+function normalizeUrl(url: string | undefined): string {
+  if (!url) return '';
+  return url.startsWith('//') ? `https:${url}` : url;
+}
+
+async function downloadMediaFile(
+  url: string,
+  filename?: string,
+  log?: Log,
+): Promise<string | null> {
+  // 仅允许 HTTPS（安全策略）
+  if (!url.startsWith('https://')) {
+    log?.debug?.(`Skipping non-HTTPS URL: ${url.slice(0, 80)}`);
+    return null;
+  }
+
+  try {
+    const result = await downloadRemoteMedia({
+      url,
+      subdir: 'qqbot/downloads',
+      originalFilename: filename,
+      maxBytes: 500 * 1024 * 1024,
+      timeoutMs: 120_000,
+    });
+    log?.debug?.(`Downloaded: ${result.path}`);
+    return result.path;
+  } catch (err) {
+    log?.error(`Download failed: ${url.slice(0, 80)} — ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}