@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/utils/attachment-tags.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+import {
+  formatAttachmentTags,
+  renderAttachmentTags,
+  TRANSCRIPT_SOURCE_LABELS,
+  type AttachmentSummary,
+} from "./attachment-tags.js";
+
+describe("engine/utils/attachment-tags", () => {
+  // ────────────────────────── shared body (mode-agnostic) ──────────────────────────
+
+  describe("shared tag body", () => {
+    it("returns empty string for missing/empty input", () => {
+      expect(formatAttachmentTags()).toBe("");
+      expect(formatAttachmentTags([])).toBe("");
+    });
+
+    it("collapses to MEDIA:{source} when a path/url is present", () => {
+      expect(formatAttachmentTags([{ type: "image", localPath: "/tmp/a.png" }])).toBe(
+        "MEDIA:/tmp/a.png",
+      );
+      expect(formatAttachmentTags([{ type: "file", url: "https://x/y.pdf" }])).toBe(
+        "MEDIA:https://x/y.pdf",
+      );
+    });
+
+    it("inlines voice transcript only for voice attachments", () => {
+      expect(
+        formatAttachmentTags([{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi" }]),
+      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi")');
+      // Non-voice attachments never get the transcript suffix even if one
+      // is present on the summary.
+      expect(
+        formatAttachmentTags([
+          { type: "image", localPath: "/tmp/i.png", transcript: "unused" } as AttachmentSummary,
+        ]),
+      ).toBe("MEDIA:/tmp/i.png");
+    });
+
+    it("falls back to bracketed tags when no source is available", () => {
+      expect(formatAttachmentTags([{ type: "image" }])).toBe("[image]");
+      expect(formatAttachmentTags([{ type: "image", filename: "a.png" }])).toBe("[image: a.png]");
+      expect(formatAttachmentTags([{ type: "voice" }])).toBe("[voice]");
+      expect(formatAttachmentTags([{ type: "voice", transcript: "t" }])).toBe(
+        '[voice (transcript: "t")]',
+      );
+      expect(formatAttachmentTags([{ type: "video" }])).toBe("[video]");
+      expect(formatAttachmentTags([{ type: "file", filename: "b.pdf" }])).toBe("[file: b.pdf]");
+      expect(formatAttachmentTags([{ type: "unknown" }])).toBe("[attachment]");
+    });
+
+    it("joins multiple entries with newline in inline mode", () => {
+      expect(
+        formatAttachmentTags([
+          { type: "image", localPath: "/tmp/a.png" },
+          { type: "voice", transcript: "hi" },
+        ]),
+      ).toBe('MEDIA:/tmp/a.png\n[voice (transcript: "hi")]');
+    });
+  });
+
+  // ────────────────────────── ref mode = body + source suffix ──────────────────────────
+
+  describe("ref mode consistency with inline", () => {
+    it("produces the same body as inline for non-voice attachments", () => {
+      const att: AttachmentSummary[] = [
+        { type: "image", localPath: "/tmp/a.png" },
+        { type: "file", filename: "b.pdf" },
+      ];
+      // Rendered one at a time so separator differences don't matter.
+      for (const a of att) {
+        expect(renderAttachmentTags([a], { mode: "inline" })).toBe(
+          renderAttachmentTags([a], { mode: "ref" }),
+        );
+      }
+    });
+
+    it("produces the same body as inline for voice without transcriptSource", () => {
+      const cases: AttachmentSummary[] = [
+        { type: "voice" },
+        { type: "voice", transcript: "hi" },
+        { type: "voice", localPath: "/tmp/v.wav", transcript: "hi" },
+      ];
+      for (const a of cases) {
+        expect(renderAttachmentTags([a], { mode: "inline" })).toBe(
+          renderAttachmentTags([a], { mode: "ref" }),
+        );
+      }
+    });
+
+    it("appends ' [source: …]' ONLY for voice + transcript + transcriptSource in ref mode", () => {
+      // ref mode: suffix appears.
+      expect(
+        renderAttachmentTags(
+          [{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi", transcriptSource: "stt" }],
+          { mode: "ref" },
+        ),
+      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi") [source: local STT]');
+
+      // inline mode: suffix NEVER appears, even with transcriptSource set.
+      expect(
+        renderAttachmentTags(
+          [{ type: "voice", localPath: "/tmp/v.wav", transcript: "hi", transcriptSource: "stt" }],
+          { mode: "inline" },
+        ),
+      ).toBe('MEDIA:/tmp/v.wav (transcript: "hi")');
+    });
+
+    it("omits the source suffix when transcriptSource is missing (both modes identical)", () => {
+      const att: AttachmentSummary = { type: "voice", transcript: "hi" };
+      expect(renderAttachmentTags([att], { mode: "ref" })).toBe(
+        renderAttachmentTags([att], { mode: "inline" }),
+      );
+    });
+
+    it("joins with space in ref mode", () => {
+      expect(
+        renderAttachmentTags(
+          [
+            { type: "image", filename: "a.png" },
+            { type: "voice", transcript: "hi" },
+          ],
+          { mode: "ref" },
+        ),
+      ).toBe('[image: a.png] [voice (transcript: "hi")]');
+    });
+  });
+
+  // ────────────────────────── Prompt-contract regression guards ──────────────────────────
+
+  describe("prompt contract", () => {
+    it("exposes the transcript-source labels table", () => {
+      expect(TRANSCRIPT_SOURCE_LABELS.stt).toBe("local STT");
+      expect(TRANSCRIPT_SOURCE_LABELS.asr).toBe("platform ASR");
+      expect(TRANSCRIPT_SOURCE_LABELS.tts).toBe("TTS source");
+      expect(TRANSCRIPT_SOURCE_LABELS.fallback).toBe("fallback text");
+    });
+
+    it("uses the single canonical keyword 'transcript:' (never 'content:')", () => {
+      // If anyone reintroduces 'content:' the regex below will match and fail the test.
+      const samples = [
+        formatAttachmentTags([{ type: "voice", transcript: "t" }]),
+        renderAttachmentTags([{ type: "voice", transcript: "t", transcriptSource: "asr" }], {
+          mode: "ref",
+        }),
+      ];
+      for (const s of samples) {
+        expect(s).toMatch(/transcript:/);
+        expect(s).not.toMatch(/content:/);
+      }
+    });
+
+    it("uses the single canonical type label 'voice' (never 'voice message')", () => {
+      const samples = [
+        renderAttachmentTags([{ type: "voice" }], { mode: "inline" }),
+        renderAttachmentTags([{ type: "voice", transcript: "hi" }], { mode: "ref" }),
+      ];
+      for (const s of samples) {
+        expect(s).not.toMatch(/voice message/);
+      }
+    });
+  });
+
+  // ────────────────────────── Options ──────────────────────────
+
+  describe("options", () => {
+    it("respects a custom separator", () => {
+      expect(
+        renderAttachmentTags(
+          [
+            { type: "image", filename: "a" },
+            { type: "video", filename: "b" },
+          ],
+          { mode: "inline", separator: " | " },
+        ),
+      ).toBe("[image: a] | [video: b]");
+    });
+
+    it("returns the emptyFallback when input is empty", () => {
+      expect(renderAttachmentTags(undefined, { mode: "ref", emptyFallback: "(none)" })).toBe(
+        "(none)",
+      );
+      expect(renderAttachmentTags([], { mode: "inline", emptyFallback: "" })).toBe("");
+    });
+  });
+});

package/src/engine/utils/attachment-tags.ts

@@ -0,0 +1,174 @@
+/**
+ * Single source of truth for rendering attachment summaries as
+ * human-readable tags that the LLM sees.
+ *
+ * There is exactly ONE vocabulary shared by every consumer:
+ *
+ *   • Type labels: `image` / `voice` / `video` / `file` / `attachment`
+ *   • Keyword for voice text: `transcript:` (never `content:`)
+ *   • With source: `MEDIA:{source}` (no bracketed alias)
+ *   • Without source: `[{type}]` or `[{type}: {filename}]`
+ *
+ * Both consumers (group history / current inbound turn, and the ref-index
+ * quoted-message block) call the same function with the same vocabulary.
+ * They differ only on two orthogonal dimensions:
+ *
+ *   1. `transcriptSource` — ref mode appends `[source: local STT]` (or
+ *      similar) after a voice transcript so the model knows where the
+ *      text came from. Inline mode omits this (the current turn knows
+ *      its own STT provenance).
+ *
+ *   2. Separator — inline joins with `\n` (history replay is multi-line),
+ *      ref joins with a space (quoted block is rendered inline).
+ *
+ * These are the ONLY permitted differences between modes. Any new
+ * decoration must be added in both modes or behind an explicit option
+ * documented here, otherwise the model ends up learning two dialects.
+ *
+ * Zero external dependencies — pure string formatting.
+ */
+
+import type { RefAttachmentSummary } from "../ref/types.js";
+
+// ============ Types ============
+
+/** Canonical attachment shape shared by history entries and ref entries. */
+export type AttachmentSummary = RefAttachmentSummary;
+
+/**
+ * Rendering mode.
+ *
+ * - `"inline"`: current turn + history replay. No transcript-source tag.
+ *   Tags are separated by newlines.
+ * - `"ref"`: quoted-message block. Appends `[source: …]` to voice
+ *   transcripts when `transcriptSource` is present. Tags are separated
+ *   by spaces so the block fits on one line.
+ */
+type RenderMode = "inline" | "ref";
+
+/** Human-readable labels for transcript provenance (prompt contract). */
+export const TRANSCRIPT_SOURCE_LABELS: Record<
+  NonNullable<RefAttachmentSummary["transcriptSource"]>,
+  string
+> = {
+  stt: "local STT",
+  asr: "platform ASR",
+  tts: "TTS source",
+  fallback: "fallback text",
+};
+
+/** Options controlling how the tag list is rendered. */
+interface RenderOptions {
+  mode: RenderMode;
+  /** Separator between tags. Defaults per mode: inline=`\n`, ref=` `. */
+  separator?: string;
+  /** Returned when `attachments` is empty/undefined. Defaults to `""`. */
+  emptyFallback?: string;
+}
+
+// ============ Public API ============
+
+/**
+ * Render a list of attachments into an LLM-facing tag string.
+ *
+ * Shared grammar (both modes):
+ *
+ * ```
+ * attachment_with_source  := "MEDIA:" SOURCE [voice_suffix]
+ * voice_suffix            := ' (transcript: "' TEXT '")' [source_suffix]
+ * attachment_no_source    := "[" TYPE_LABEL [": " FILENAME] [voice_suffix_bare] "]" [source_suffix_bare]
+ * voice_suffix_bare       := ' (transcript: "' TEXT '")'
+ * source_suffix           := " [source: " LABEL "]"   ← ref mode only
+ * source_suffix_bare      := " [source: " LABEL "]"   ← ref mode only
+ * TYPE_LABEL              := "image" | "voice" | "video" | "file" | "attachment"
+ * ```
+ *
+ * The **only** mode-dependent decoration is the `source_suffix` (present
+ * in `ref`, absent in `inline`). Every other token is identical.
+ */
+export function renderAttachmentTags(
+  attachments: readonly AttachmentSummary[] | undefined,
+  options: RenderOptions,
+): string {
+  if (!attachments?.length) {
+    return options.emptyFallback ?? "";
+  }
+
+  const parts: string[] = [];
+  for (const att of attachments) {
+    parts.push(renderOne(att, options.mode));
+  }
+
+  const separator = options.separator ?? (options.mode === "ref" ? " " : "\n");
+  return parts.join(separator);
+}
+
+/**
+ * Shorthand for `renderAttachmentTags(attachments, { mode: "inline" })`.
+ *
+ * Kept as the primary entry point for group history / current-turn
+ * rendering where the terse inline form is always wanted.
+ */
+export function formatAttachmentTags(attachments?: readonly AttachmentSummary[]): string {
+  return renderAttachmentTags(attachments, { mode: "inline" });
+}
+
+// ============ Internal ============
+
+/**
+ * Render a single attachment.
+ *
+ * The function is split into two orthogonal concerns:
+ *   - `renderBody`: the shared "MEDIA:{source}…" or "[type…]" string.
+ *   - `renderSourceSuffix`: ref-mode-only `" [source: …]"` tail.
+ *
+ * Both consumers produce the same body; only the suffix differs.
+ */
+function renderOne(att: AttachmentSummary, mode: RenderMode): string {
+  const body = renderBody(att);
+  const suffix = mode === "ref" ? renderSourceSuffix(att) : "";
+  return body + suffix;
+}
+
+/** Shared, mode-agnostic body of the tag. */
+function renderBody(att: AttachmentSummary): string {
+  const source = att.localPath || att.url;
+  const voiceSuffix =
+    att.type === "voice" && att.transcript ? ` (transcript: "${att.transcript}")` : "";
+
+  if (source) {
+    return `MEDIA:${source}${voiceSuffix}`;
+  }
+
+  const label = labelForType(att.type);
+  const namePart = att.filename ? `: ${att.filename}` : "";
+  return `[${label}${namePart}${voiceSuffix}]`;
+}
+
+/**
+ * Ref-mode-only tail that records where a voice transcript came from.
+ * Empty string when the attachment isn't a transcribed voice message.
+ */
+function renderSourceSuffix(att: AttachmentSummary): string {
+  if (att.type !== "voice" || !att.transcript || !att.transcriptSource) {
+    return "";
+  }
+  const label = TRANSCRIPT_SOURCE_LABELS[att.transcriptSource] ?? att.transcriptSource;
+  return ` [source: ${label}]`;
+}
+
+/** Canonical single-word label for each attachment type. */
+function labelForType(type: AttachmentSummary["type"]): string {
+  switch (type) {
+    case "image":
+      return "image";
+    case "voice":
+      return "voice";
+    case "video":
+      return "video";
+    case "file":
+      return "file";
+    default:
+      return "attachment";
+  }
+}

package/src/engine/utils/audio.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, it } from "vitest";
+import {
+  pcmToWav,
+  stripAmrHeader,
+  isVoiceAttachment,
+  isAudioFile,
+  shouldTranscodeVoice,
+  parseWavFallback,
+} from "./audio.js";
+
+describe("engine/utils/audio", () => {
+  describe("pcmToWav", () => {
+    it("produces a valid WAV header", () => {
+      const pcm = new Uint8Array([0, 0, 1, 0]);
+      const wav = pcmToWav(pcm, 24000);
+
+      expect(wav.toString("ascii", 0, 4)).toBe("RIFF");
+      expect(wav.toString("ascii", 8, 12)).toBe("WAVE");
+      expect(wav.toString("ascii", 12, 16)).toBe("fmt ");
+      expect(wav.toString("ascii", 36, 40)).toBe("data");
+    });
+
+    it("sets correct file size in RIFF header", () => {
+      const pcm = new Uint8Array(100);
+      const wav = pcmToWav(pcm, 24000);
+      const riffSize = wav.readUInt32LE(4);
+      expect(riffSize).toBe(wav.length - 8);
+    });
+
+    it("sets correct sample rate", () => {
+      const pcm = new Uint8Array(10);
+      const wav = pcmToWav(pcm, 48000);
+      expect(wav.readUInt32LE(24)).toBe(48000);
+    });
+
+    it("sets correct channel count", () => {
+      const pcm = new Uint8Array(10);
+      const wav = pcmToWav(pcm, 24000, 2);
+      expect(wav.readUInt16LE(22)).toBe(2);
+    });
+
+    it("embeds PCM data after the 44-byte header", () => {
+      const pcm = new Uint8Array([0x01, 0x02, 0x03, 0x04]);
+      const wav = pcmToWav(pcm, 24000);
+      expect(wav[44]).toBe(0x01);
+      expect(wav[45]).toBe(0x02);
+      expect(wav[46]).toBe(0x03);
+      expect(wav[47]).toBe(0x04);
+    });
+
+    it("sets data chunk size matching PCM length", () => {
+      const pcm = new Uint8Array(256);
+      const wav = pcmToWav(pcm, 24000);
+      const dataSize = wav.readUInt32LE(40);
+      expect(dataSize).toBe(256);
+    });
+  });
+
+  describe("stripAmrHeader", () => {
+    it("strips the #!AMR header when present", () => {
+      const amrHeader = Buffer.from("#!AMR\n");
+      const payload = Buffer.from([0x01, 0x02, 0x03]);
+      const buf = Buffer.concat([amrHeader, payload]);
+
+      const result = stripAmrHeader(buf);
+      expect(result).toEqual(payload);
+    });
+
+    it("returns the buffer unchanged when no AMR header", () => {
+      const buf = Buffer.from([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07]);
+      const result = stripAmrHeader(buf);
+      expect(result).toBe(buf);
+    });
+
+    it("returns the buffer unchanged when too short", () => {
+      const buf = Buffer.from([0x01, 0x02]);
+      const result = stripAmrHeader(buf);
+      expect(result).toBe(buf);
+    });
+  });
+
+  describe("isVoiceAttachment", () => {
+    it("detects voice content_type", () => {
+      expect(isVoiceAttachment({ content_type: "voice" })).toBe(true);
+    });
+
+    it("detects audio/* content_type", () => {
+      expect(isVoiceAttachment({ content_type: "audio/silk" })).toBe(true);
+      expect(isVoiceAttachment({ content_type: "audio/amr" })).toBe(true);
+    });
+
+    it("detects voice file extensions", () => {
+      expect(isVoiceAttachment({ filename: "msg.amr" })).toBe(true);
+      expect(isVoiceAttachment({ filename: "msg.silk" })).toBe(true);
+      expect(isVoiceAttachment({ filename: "msg.slk" })).toBe(true);
+      expect(isVoiceAttachment({ filename: "msg.slac" })).toBe(true);
+    });
+
+    it("rejects non-voice attachments", () => {
+      expect(isVoiceAttachment({ content_type: "image/png" })).toBe(false);
+      expect(isVoiceAttachment({ filename: "photo.jpg" })).toBe(false);
+    });
+
+    it("handles missing fields", () => {
+      expect(isVoiceAttachment({})).toBe(false);
+    });
+  });
+
+  describe("isAudioFile", () => {
+    it.each([
+      ".silk",
+      ".slk",
+      ".amr",
+      ".wav",
+      ".mp3",
+      ".ogg",
+      ".opus",
+      ".aac",
+      ".flac",
+      ".m4a",
+      ".wma",
+      ".pcm",
+    ])("recognizes %s as audio", (ext) => {
+      expect(isAudioFile(`file${ext}`)).toBe(true);
+    });
+
+    it("recognizes audio MIME types", () => {
+      expect(isAudioFile("file.bin", "audio/mpeg")).toBe(true);
+      expect(isAudioFile("file.bin", "voice")).toBe(true);
+    });
+
+    it("rejects non-audio files", () => {
+      expect(isAudioFile("photo.jpg")).toBe(false);
+      expect(isAudioFile("doc.pdf")).toBe(false);
+    });
+
+    it("is case-insensitive on extensions", () => {
+      expect(isAudioFile("file.MP3")).toBe(true);
+      expect(isAudioFile("file.Wav")).toBe(true);
+    });
+  });
+
+  describe("shouldTranscodeVoice", () => {
+    it("returns false for QQ native MIME types", () => {
+      expect(shouldTranscodeVoice("file.bin", "audio/silk")).toBe(false);
+      expect(shouldTranscodeVoice("file.bin", "audio/amr")).toBe(false);
+      expect(shouldTranscodeVoice("file.bin", "audio/wav")).toBe(false);
+      expect(shouldTranscodeVoice("file.bin", "audio/mp3")).toBe(false);
+    });
+
+    it("returns false for QQ native extensions", () => {
+      expect(shouldTranscodeVoice("voice.silk")).toBe(false);
+      expect(shouldTranscodeVoice("voice.amr")).toBe(false);
+      expect(shouldTranscodeVoice("voice.wav")).toBe(false);
+      expect(shouldTranscodeVoice("voice.mp3")).toBe(false);
+    });
+
+    it("returns true for non-native audio formats", () => {
+      expect(shouldTranscodeVoice("voice.ogg")).toBe(true);
+      expect(shouldTranscodeVoice("voice.opus")).toBe(true);
+      expect(shouldTranscodeVoice("voice.flac")).toBe(true);
+      expect(shouldTranscodeVoice("voice.aac")).toBe(true);
+    });
+
+    it("returns false for non-audio files", () => {
+      expect(shouldTranscodeVoice("photo.jpg")).toBe(false);
+      expect(shouldTranscodeVoice("doc.txt")).toBe(false);
+    });
+  });
+
+  describe("parseWavFallback", () => {
+    function buildMinimalWav(pcmData: Buffer, sampleRate = 24000, channels = 1): Buffer {
+      const bitsPerSample = 16;
+      const byteRate = sampleRate * channels * (bitsPerSample / 8);
+      const blockAlign = channels * (bitsPerSample / 8);
+      const dataSize = pcmData.length;
+      const buf = Buffer.alloc(44 + dataSize);
+
+      buf.write("RIFF", 0);
+      buf.writeUInt32LE(36 + dataSize, 4);
+      buf.write("WAVE", 8);
+      buf.write("fmt ", 12);
+      buf.writeUInt32LE(16, 16);
+      buf.writeUInt16LE(1, 20);
+      buf.writeUInt16LE(channels, 22);
+      buf.writeUInt32LE(sampleRate, 24);
+      buf.writeUInt32LE(byteRate, 28);
+      buf.writeUInt16LE(blockAlign, 32);
+      buf.writeUInt16LE(bitsPerSample, 34);
+      buf.write("data", 36);
+      buf.writeUInt32LE(dataSize, 40);
+      pcmData.copy(buf, 44);
+      return buf;
+    }
+
+    it("extracts PCM from a valid mono 24kHz WAV", () => {
+      const pcm = Buffer.from([0x01, 0x00, 0x02, 0x00]);
+      const wav = buildMinimalWav(pcm, 24000, 1);
+      const result = parseWavFallback(wav);
+      expect(result).not.toBeNull();
+      expect(result!.length).toBe(4);
+      expect(result![0]).toBe(0x01);
+      expect(result![1]).toBe(0x00);
+    });
+
+    it("returns null for buffers shorter than 44 bytes", () => {
+      expect(parseWavFallback(Buffer.alloc(20))).toBeNull();
+    });
+
+    it("returns null for non-WAV data", () => {
+      const buf = Buffer.alloc(44);
+      buf.write("NOT_", 0);
+      expect(parseWavFallback(buf)).toBeNull();
+    });
+
+    it("returns null for non-PCM audio formats", () => {
+      const wav = buildMinimalWav(Buffer.alloc(4), 24000, 1);
+      wav.writeUInt16LE(3, 20); // IEEE float instead of PCM
+      expect(parseWavFallback(wav)).toBeNull();
+    });
+
+    it("downmixes stereo to mono", () => {
+      // 2 samples × 2 channels × 2 bytes = 8 bytes
+      const stereoPcm = Buffer.alloc(8);
+      const view = new DataView(stereoPcm.buffer);
+      view.setInt16(0, 100, true); // L sample 0
+      view.setInt16(2, 200, true); // R sample 0
+      view.setInt16(4, -100, true); // L sample 1
+      view.setInt16(6, -200, true); // R sample 1
+
+      const wav = buildMinimalWav(stereoPcm, 24000, 2);
+      const result = parseWavFallback(wav);
+      expect(result).not.toBeNull();
+      // mono output: 2 samples × 2 bytes = 4 bytes
+      expect(result!.length).toBe(4);
+      const outView = new DataView(result!.buffer, result!.byteOffset);
+      expect(outView.getInt16(0, true)).toBe(150); // (100+200)/2
+      expect(outView.getInt16(2, true)).toBe(-150); // (-100+-200)/2
+    });
+
+    it("resamples non-24kHz WAV to 24kHz", () => {
+      // 4 samples at 48kHz → should produce ~2 samples at 24kHz
+      const pcm48k = Buffer.alloc(8);
+      const wav = buildMinimalWav(pcm48k, 48000, 1);
+      const result = parseWavFallback(wav);
+      expect(result).not.toBeNull();
+      expect(result!.length).toBe(4); // 2 samples × 2 bytes
+    });
+  });
+});