@jerryliang122/openclaw-qqbot 1.0.0

package/src/dispatch/body-assembler.ts

@@ -0,0 +1,308 @@
+/**
+ * Body 组装器（消息入站 body 组装）
+ *
+ * SDK 中间件链已经完成了所有预处理：
+ *   - ctx.message.content              ← contentSanitizer（face 解析 + mention 清洗）
+ *   - ctx.state.quote                  ← quoteRef
+ *   - ctx.state.history                ← historyBuffer
+ *   - ctx.state.mention                ← mentionGate
+ *   - ctx.state.processedAttachments   ← attachmentProcessor（语音 STT、图片 URL）
+ *
+ * 本模块仅负责"按框架协议把上述上下文拼成最终字符串"，是纯函数。
+ *
+ * 输出字段语义（与框架 buildCtxPayload 语义一致）：
+ *   - webBody    → ctxPayload.Body         （Web UI 展示）
+ *   - agentBody  → ctxPayload.BodyForAgent （AI 看到的）
+ *   - rawBody    → ctxPayload.RawBody / CommandBody（命令解析、审计）
+ *   - systemPrompt → ctxPayload.GroupSystemPrompt
+ */
+import type {
+  MiddlewareContext,
+  QQBotInboundMessage,
+  ResolvedQuote,
+  HistoryEntry,
+} from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { ProcessedAttachments } from '../middleware/attachment.js';
+import { getAdapters } from '../adapter/resolve.js';
+
+// ── 协议常量 ─────────────────────────────
+const QUOTE_BEGIN = '[Quoted message begins]';
+const QUOTE_END = '[Quoted message ends]';
+const REF_BEGIN = '[Reference message begins]';
+const REF_END = '[Reference message ends]';
+const HISTORY_BEGIN = '[Chat history begins]';
+const HISTORY_END = '[Chat history ends]';
+const CURRENT_MSG = '[Current message]';
+
+export interface AssembledBody {
+  /** Web UI 展示用 body */
+  webBody: string;
+  /** AI 实际接收的 body（dynamicCtx + userMessage [+ history 前缀]） */
+  agentBody: string;
+  /** 原始 content（命令解析 / 审计用） */
+  rawBody: string;
+  /** 群系统提示（account.systemPrompt + 群级提示拼接） */
+  systemPrompt?: string;
+}
+
+/**
+ * 把 SDK 中间件链产出的所有上下文组装为框架规约的 body。
+ */
+export function assembleBody(
+  ctx: MiddlewareContext,
+  msg: QQBotInboundMessage,
+  account: ResolvedQQBotAccount,
+  getRuntime?: () => any,
+): AssembledBody {
+  const rawBody = msg.content ?? '';
+  const isGroup = msg.kind === 'group';
+
+  const mentionState = ctx.state.mention as { wasMentioned?: boolean } | undefined;
+  const wasMentioned = mentionState?.wasMentioned ?? false;
+  const processed = ctx.state.processedAttachments as ProcessedAttachments | undefined;
+  const quote = ctx.state.quote as ResolvedQuote | undefined;
+  const history = ctx.state.history as HistoryEntry[] | undefined;
+
+  // ── Layer 1: userContent（清洗后的文本 + 语音转录 + 附件描述） ──
+  const userContent = buildUserContent(ctx.message.content ?? '', processed);
+
+  // ── Layer 2: quotePart ──
+  const quotePart = buildQuotePart(quote);
+
+  // ── Layer 3: userMessage（群带 [sender] 前缀 + (@you)） ──
+  const userMessage = buildUserMessage({ msg, userContent, quotePart, isGroup, wasMentioned });
+
+  // ── Layer 4: dynamicCtx（媒体元数据块 + msg_elements 上下文） ──
+  const dynamicCtx = buildDynamicCtx(processed, msg, quote);
+
+  // ── Layer 5: agentBody（命令直通 / 群被@时前置历史） ──
+  const agentBody = buildAgentBody({
+    userContent,
+    base: dynamicCtx + userMessage,
+    isGroup,
+    wasMentioned,
+    history,
+  });
+
+  // ── webBody ──
+  const bodyContent = `${quotePart}${userContent}`;
+
+  // ── webBody 外层 envelope 渲染（用 formatInboundEnvelope 包装） ──
+  const webBody = getRuntime
+    ? renderWebBody(getRuntime, bodyContent, msg, isGroup)
+    : bodyContent;
+
+  const systemPrompt = account.systemPrompt?.trim() || undefined;
+
+  return { webBody, agentBody, rawBody, systemPrompt };
+}
+
+// ── 局部组装函数 ─────────────────────────────────────────────
+
+/** Layer 1：sanitized + 语音转录 + 附件描述 */
+function buildUserContent(sanitizedRaw: string, processed: ProcessedAttachments | undefined): string {
+  const sanitized = sanitizedRaw.trim();
+  const voiceText = processed?.voiceText ?? '';
+  const attachmentInfo = processed?.otherInfo ? `\n${processed.otherInfo}` : '';
+
+  if (voiceText) {
+    return (sanitized ? `${sanitized}\n${voiceText}` : voiceText) + attachmentInfo;
+  }
+  return sanitized + attachmentInfo;
+}
+
+/** Layer 2：[Quoted message begins]…[Quoted message ends] */
+function buildQuotePart(quote: ResolvedQuote | undefined): string {
+  if (!quote) return '';
+  const text = quote.text || 'Original content unavailable';
+  return `${QUOTE_BEGIN}\n${text}\n${QUOTE_END}\n${CURRENT_MSG}\n`;
+}
+
+/** Layer 3：quote + [Sender] {content}{(@you)?} */
+function buildUserMessage(input: {
+  msg: QQBotInboundMessage;
+  userContent: string;
+  quotePart: string;
+  isGroup: boolean;
+  wasMentioned: boolean;
+}): string {
+  const { msg, userContent, quotePart, isGroup, wasMentioned } = input;
+  const atYouTag = isGroup && wasMentioned ? ' (@you)' : '';
+
+  if (isGroup) {
+    const senderLabel = formatSenderLabel(msg.senderName, msg.senderId);
+    return `${quotePart}[${senderLabel}] ${userContent}${atYouTag}`;
+  }
+  return `${quotePart}${userContent}`;
+}
+
+/** Layer 3（合并版）：消息合并处理已移除——群消息合并完全交给框架队列
+ * （coalesce.enabled → dispatch 侧 queueModeOverride collect/followup）。
+ */
+
+/** Layer 4：- Images / - Voice / - ASR 元数据块 + msg_elements 引用上下文 */
+function buildDynamicCtx(
+  processed: ProcessedAttachments | undefined,
+  msg: QQBotInboundMessage,
+  quote: ResolvedQuote | undefined,
+): string {
+  const lines: string[] = [];
+
+  // Images
+  if (processed?.imageUrls.length) {
+    lines.push(`- Images: ${processed.imageUrls.join(', ')}`);
+  }
+
+  // Voice：从 transcripts 行存投影出 paths + urls，去重后拼接
+  const transcripts = processed?.transcripts ?? [];
+  const voiceRefs = unique([
+    ...transcripts.map((t) => t.localPath).filter(isNonEmpty),
+    ...transcripts.map((t) => t.remoteUrl).filter(isNonEmpty),
+  ]);
+  if (voiceRefs.length > 0) {
+    lines.push(`- Voice: ${voiceRefs.join(', ')}`);
+  }
+
+  // ASR：source==='asr' 的 text，或任意 transcript 上的 asrReferText
+  const asrTexts = unique(
+    transcripts
+      .map((t) => (t.source === 'asr' ? t.text : t.asrReferText))
+      .filter(isNonEmpty),
+  );
+  if (asrTexts.length > 0) {
+    lines.push(`- ASR: ${asrTexts.join(' | ')}`);
+  }
+
+  // msg_elements 上下文（引用内容本身来自 msg_elements[0] 时跳过该元素避免重复，
+  // 其余元素——如 AT+最近N 模式平台附带的消息记录——仍照常渲染）
+  const quoteConsumedFirstElement = quote?.source === 'msg_elements';
+  const elementsCtx = buildMsgElementsContext(msg, quoteConsumedFirstElement);
+  if (elementsCtx.length > 0) {
+    lines.push(REF_BEGIN, ...elementsCtx, REF_END);
+  }
+
+  return lines.length > 0 ? `${lines.join('\n')}\n\n` : '';
+}
+
+/** 检测平台预渲染文本（示例3形态：`=== 消息 1 ===` + `[消息内容]` 行） */
+function isPlatformPrerenderedContent(content: string): boolean {
+  return /^===\s*消息\s*\d+\s*===/.test(content.trimStart()) && content.includes('[消息内容]');
+}
+
+/** 从 msg_elements 提取上下文（非引用消息也解析，如被回复的 bot 消息等） */
+function buildMsgElementsContext(msg: QQBotInboundMessage, skipFirstElement = false): string[] {
+  const elements = msg.msgElements;
+  if (!elements || elements.length === 0) return [];
+
+  const lines: string[] = [];
+  let index = 0;
+  for (let i = 0; i < elements.length; i++) {
+    if (skipFirstElement && i === 0) continue;
+    const el = elements[i]!;
+    const content = el.content?.trim();
+    const attachments = Array.isArray(el.attachments) ? el.attachments : [];
+    if (!content && attachments.length === 0) continue;
+    index += 1;
+
+    // 平台已预渲染的多消息文本（如聊天记录转发）直接透传，避免二次包裹
+    if (content && isPlatformPrerenderedContent(content)) {
+      lines.push(`=== 消息记录 ${index} ===`, content);
+      continue;
+    }
+
+    const author = (el as Record<string, unknown>).author as
+      | { username?: string }
+      | undefined;
+    const sender = author?.username ?? '未知';
+
+    lines.push(
+      `=== 消息 ${index} ===`,
+      `[消息内容] ${content || '（无文本）'}`,
+    );
+    for (const att of attachments) {
+      const a = att as { url?: string; content_type?: string };
+      const kind = a.content_type ?? 'attachment';
+      const url = a.url ?? '';
+      lines.push(`[附件] ${kind}${url ? `: ${url}` : ''}`);
+    }
+    lines.push(`[发送者] ${sender}`);
+  }
+
+  return lines;
+}
+
+function unique<T>(arr: T[]): T[] {
+  return [...new Set(arr)];
+}
+
+function isNonEmpty(x: string | undefined): x is string {
+  return typeof x === 'string' && x.length > 0;
+}
+
+/** Layer 5：base = dynamicCtx+userMessage；命令直通；群被@叠历史前缀 */
+function buildAgentBody(input: {
+  userContent: string;
+  base: string;
+  isGroup: boolean;
+  wasMentioned: boolean;
+  history: HistoryEntry[] | undefined;
+}): string {
+  const { userContent, base, isGroup, wasMentioned, history } = input;
+
+  // 斜杠命令直通：去除一切装饰及首尾空白
+  if (userContent.trim().startsWith('/')) {
+    return userContent;
+  }
+
+  // 群被@ + 有历史 → 叠历史前缀
+  if (isGroup && wasMentioned && history && history.length > 0) {
+    const historyText = history
+      .map((h) => {
+        const label = formatSenderLabel(h.senderName, h.senderId);
+        return `[${label}] ${h.content}`;
+      })
+      .join('\n');
+    return [HISTORY_BEGIN, historyText, '', HISTORY_END, CURRENT_MSG, base].join('\n');
+  }
+
+  return base;
+}
+
+/** "Nick (openid)" 标签；当 name 已含 id 时避免双重包裹 */
+function formatSenderLabel(name: string | undefined, id: string): string {
+  if (!name) return id;
+  return name.includes(id) ? name : `${name} (${id})`;
+}
+
+/** webBody 外层 envelope 渲染 */
+function renderWebBody(
+  getRuntime: () => any,
+  bodyContent: string,
+  msg: QQBotInboundMessage,
+  isGroup: boolean,
+): string {
+  try {
+    const { formatEnvelope } = getAdapters(getRuntime());
+    if (!formatEnvelope) return bodyContent;
+    return formatEnvelope({
+      channel: 'qqbot',
+      from: msg.senderName ?? msg.senderId,
+      timestamp: normalizeTimestamp(msg.timestamp),
+      body: bodyContent,
+      chatType: isGroup ? 'group' : 'direct',
+    });
+  } catch {
+    return bodyContent;
+  }
+}
+
+/** timestamp 归一化到 epoch ms */
+function normalizeTimestamp(ts: string | number | undefined): number {
+  if (typeof ts === 'number') return ts;
+  if (typeof ts === 'string') {
+    const d = new Date(ts).getTime();
+    if (!Number.isNaN(d)) return d;
+  }
+  return Date.now();
+}

package/src/dispatch/ctx-builder.ts

@@ -0,0 +1,127 @@
+/**
+ * ctxPayload 构建器
+ *
+ * 与内置版 outbound-dispatch.ts:buildCtxPayload 对齐，
+ * 将 SDK 消息数据转换为 OpenClaw 框架标准的入站上下文。
+ */
+import type { MiddlewareContext, QQBotInboundMessage } from '@tencent-connect/qqbot-nodejs';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { AssembledBody } from './body-assembler.js';
+import type { OpenClawInboundMessage } from './envelope-builder.js';
+import type { RuntimeAdapters } from '../adapter/resolve.js';
+
+export interface CtxPayloadParams {
+  assembled: AssembledBody;
+  envelope: OpenClawInboundMessage;
+  route: { sessionKey: string; accountId: string; agentId?: string };
+  msg: QQBotInboundMessage;
+  ctx: MiddlewareContext;
+  adapters: RuntimeAdapters;
+}
+
+export function buildCtxPayload(params: CtxPayloadParams): any {
+  const { assembled, envelope, route, msg, ctx, adapters } = params;
+
+  const isSlashCommand = /^\//.test(assembled.rawBody ?? '');
+  const convKind = envelope.chatScope === 'group' ? 'group' : 'direct';
+  const peerId = convKind === 'group'
+    ? (envelope.groupId ?? envelope.senderId)
+    : envelope.senderId;
+  const groupId = convKind === 'group' ? envelope.groupId : undefined;
+
+  const processed = ctx.state.processedAttachments as any;
+
+  /**
+   * 正规媒体通道（对齐 core ChannelInboundMediaInput）：
+   * 全部附件（图片/语音/文件）按原始顺序作为 media facts 传入，
+   * 字段名必须是 path（不是 localPath）；url 用本地路径（QQ CDN URL 有时效），
+   * 与 telegram toInboundMedia 的 { path, url: path, contentType, kind, transcribed } 一致。
+   * media facts 经 core 归一化后生成 MediaPath/MediaPaths/MediaTypes/MediaTranscribedIndexes。
+   */
+  const mediaFacts = (processed?.media as Array<{
+    kind: 'image' | 'audio' | 'video' | 'document';
+    localPath?: string;
+    remoteUrl?: string;
+    contentType?: string;
+    transcribed?: boolean;
+  }> | undefined)?.map((m) => ({
+    kind: m.kind,
+    ...(m.localPath
+      ? { path: m.localPath, url: m.localPath }
+      : m.remoteUrl
+        ? { url: m.remoteUrl }
+        : {}),
+    ...(m.contentType ? { contentType: m.contentType } : {}),
+    ...(m.transcribed ? { transcribed: true } : {}),
+  })) ?? [];
+
+  const msgTimestamp = (msg as any).timestamp ?? (msg as any).Timestamp;
+
+  // 群成员角色（平台 member_role：admin/owner）→ sender.roles，
+  // 供框架群权限/工具策略分级使用；c2c / 未标注为空
+  const memberRole = (msg as { raw?: { author?: { member_role?: string } } }).raw?.author?.member_role;
+  const senderRoles = memberRole === 'admin' || memberRole === 'owner' ? [memberRole] : undefined;
+
+  return adapters.buildInboundContext?.({
+    channel: 'qqbot',
+    accountId: route.accountId,
+    provider: 'qqbot',
+    surface: 'qqbot',
+    messageId: envelope.messageId,
+    timestamp: msgTimestamp ? new Date(msgTimestamp).getTime() : Date.now(),
+    from: envelope.targetId,
+    sender: { id: envelope.senderId, name: envelope.senderName, ...(senderRoles ? { roles: senderRoles } : {}) },
+    conversation: {
+      kind: convKind,
+      id: peerId,
+      label: assembled.systemPrompt,
+    },
+    message: {
+      body: assembled.webBody,
+      bodyForAgent: assembled.agentBody,
+      rawBody: assembled.rawBody,
+      commandBody: assembled.rawBody,
+    },
+    route: {
+      agentId: route.agentId ?? 'default',
+      routeSessionKey: route.sessionKey,
+      accountId: route.accountId,
+    },
+    reply: {
+      to: envelope.targetId,
+      replyToId: envelope.messageId,
+      originatingTo: envelope.targetId,
+    },
+    access: {
+      commands: { authorized: isSlashCommand },
+    },
+    command: isSlashCommand
+      ? { kind: 'text-slash' as const, body: assembled.rawBody!, authorized: true }
+      : undefined,
+    media: mediaFacts.length > 0 ? mediaFacts : undefined,
+    supplemental: {
+      quote: envelope.quote
+        ? { id: envelope.messageId, body: envelope.quote.content, sender: envelope.quote.senderId }
+        : undefined,
+      groupSystemPrompt: envelope.systemPrompt,
+    },
+    extra: {
+      ...(isSlashCommand ? { CommandSource: 'text' } : {}),
+      ...(groupId ? { QQGroupOpenid: groupId } : {}),
+      ...(processed?.localMediaPaths?.length
+        ? {
+            MediaPaths: processed.localMediaPaths,
+            MediaPath: processed.localMediaPaths[0],
+            MediaTypes: processed.localMediaTypes,
+            MediaType: processed.localMediaTypes?.[0],
+          }
+        : {}),
+      ...(processed?.remoteMediaUrls?.length
+        ? {
+            MediaUrls: processed.remoteMediaUrls,
+            MediaUrl: processed.remoteMediaUrls[0],
+          }
+        : {}),
+    },
+  });
+}