@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.2

package/src/engine/group/message-gating.test.ts

@@ -1,188 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  resolveGroupMessageGate,
-  type GroupMessageGateInput,
-  type GroupMessageGateResult,
-} from "./message-gating.js";
-
-// Compose a full input so each test can override just the interesting axis.
-function input(overrides: Partial<GroupMessageGateInput>): GroupMessageGateInput {
-  return {
-    ignoreOtherMentions: false,
-    hasAnyMention: false,
-    wasMentioned: false,
-    implicitMention: false,
-    allowTextCommands: true,
-    isControlCommand: false,
-    commandAuthorized: false,
-    requireMention: true,
-    canDetectMention: true,
-    ...overrides,
-  };
-}
-
-function expectAction(
-  result: GroupMessageGateResult,
-  action: GroupMessageGateResult["action"],
-): void {
-  expect(result.action).toBe(action);
-}
-
-describe("engine/group/message-gating", () => {
-  describe("Layer 1: ignoreOtherMentions", () => {
-    it("drops messages that @other users when enabled", () => {
-      const result = resolveGroupMessageGate(
-        input({ ignoreOtherMentions: true, hasAnyMention: true }),
-      );
-      expectAction(result, "drop_other_mention");
-    });
-
-    it("does NOT drop when the bot itself was @-ed", () => {
-      const result = resolveGroupMessageGate(
-        input({ ignoreOtherMentions: true, hasAnyMention: true, wasMentioned: true }),
-      );
-      expectAction(result, "pass");
-    });
-
-    it("does NOT drop when implicitly mentioned via quote", () => {
-      const result = resolveGroupMessageGate(
-        input({ ignoreOtherMentions: true, hasAnyMention: true, implicitMention: true }),
-      );
-      expectAction(result, "pass");
-    });
-
-    it("is inactive when ignoreOtherMentions is off", () => {
-      const result = resolveGroupMessageGate(
-        input({ ignoreOtherMentions: false, hasAnyMention: true }),
-      );
-      // Falls through to mention gate — requireMention on, so skipped.
-      expectAction(result, "skip_no_mention");
-    });
-  });
-
-  describe("Layer 2: unauthorized control command", () => {
-    it("silently blocks an unauthorized /stop", () => {
-      const result = resolveGroupMessageGate(
-        input({ isControlCommand: true, commandAuthorized: false }),
-      );
-      expectAction(result, "block_unauthorized_command");
-    });
-
-    it("passes through when sender is authorized", () => {
-      const result = resolveGroupMessageGate(
-        input({ isControlCommand: true, commandAuthorized: true, wasMentioned: true }),
-      );
-      expectAction(result, "pass");
-    });
-
-    it("does not trigger when text commands are disabled", () => {
-      const result = resolveGroupMessageGate(
-        input({
-          allowTextCommands: false,
-          isControlCommand: true,
-          commandAuthorized: false,
-          wasMentioned: true,
-        }),
-      );
-      // allowTextCommands=false skips the block, so the mention gate decides.
-      expectAction(result, "pass");
-    });
-  });
-
-  describe("Layer 3: mention gating", () => {
-    it("requires @bot when requireMention is on", () => {
-      const result = resolveGroupMessageGate(input({ requireMention: true }));
-      expectAction(result, "skip_no_mention");
-      expect(result.effectiveWasMentioned).toBe(false);
-    });
-
-    it("passes through when explicitly mentioned", () => {
-      const result = resolveGroupMessageGate(input({ requireMention: true, wasMentioned: true }));
-      expectAction(result, "pass");
-      expect(result.effectiveWasMentioned).toBe(true);
-    });
-
-    it("passes through on implicit mention", () => {
-      const result = resolveGroupMessageGate(
-        input({ requireMention: true, implicitMention: true }),
-      );
-      expectAction(result, "pass");
-      expect(result.effectiveWasMentioned).toBe(true);
-    });
-
-    it("passes through when requireMention is off", () => {
-      const result = resolveGroupMessageGate(input({ requireMention: false }));
-      expectAction(result, "pass");
-    });
-
-    it("passes through when mention cannot be detected (DMs)", () => {
-      const result = resolveGroupMessageGate(
-        input({ requireMention: true, canDetectMention: false }),
-      );
-      expectAction(result, "pass");
-    });
-  });
-
-  describe("command bypass", () => {
-    it("bypasses mention gate for an authorized control command", () => {
-      const result = resolveGroupMessageGate(
-        input({
-          requireMention: true,
-          isControlCommand: true,
-          commandAuthorized: true,
-          allowTextCommands: true,
-        }),
-      );
-      expectAction(result, "pass");
-      expect(result.shouldBypassMention).toBe(true);
-      expect(result.effectiveWasMentioned).toBe(true);
-    });
-
-    it("does NOT bypass when the command @-s another user", () => {
-      const result = resolveGroupMessageGate(
-        input({
-          requireMention: true,
-          isControlCommand: true,
-          commandAuthorized: true,
-          hasAnyMention: true,
-        }),
-      );
-      expectAction(result, "skip_no_mention");
-      expect(result.shouldBypassMention).toBe(false);
-    });
-
-    it("is a no-op when requireMention is off", () => {
-      const result = resolveGroupMessageGate(
-        input({
-          requireMention: false,
-          isControlCommand: true,
-          commandAuthorized: true,
-        }),
-      );
-      expectAction(result, "pass");
-      // requireMention=false means bypass is unnecessary (condition 1 fails).
-      expect(result.shouldBypassMention).toBe(false);
-    });
-  });
-
-  describe("priority ordering", () => {
-    it("layer 1 wins over layer 2 (ignoreOtherMentions before block)", () => {
-      const result = resolveGroupMessageGate(
-        input({
-          ignoreOtherMentions: true,
-          hasAnyMention: true,
-          isControlCommand: true,
-          commandAuthorized: false,
-        }),
-      );
-      expectAction(result, "drop_other_mention");
-    });
-
-    it("layer 2 wins over layer 3 (unauthorized command before skip)", () => {
-      const result = resolveGroupMessageGate(
-        input({ requireMention: true, isControlCommand: true, commandAuthorized: false }),
-      );
-      expectAction(result, "block_unauthorized_command");
-    });
-  });
-});

package/src/engine/group/message-gating.ts

@@ -1,216 +0,0 @@
-/**
- * Group message gate — unified entry point for group inbound gating.
- *
- * Collapses three orthogonal rules that previously lived in ad-hoc spots
- * of the standalone gateway into a single pure function. Callers pass in
- * the message's mention state plus the resolved configuration, and get
- * back a structured action telling them how to handle the message.
- *
- * Evaluation order (short-circuit at the first match):
- *   1. `ignoreOtherMentions` — message @-s someone else but not the bot
- *                              → `drop_other_mention` (record to history,
- *                              then drop). Implicit mentions (e.g. quoting
- *                              a bot reply) still count as @bot.
- *   2. `block_unauthorized_command` — sender is not allowed to run control
- *                                     commands (text starts with `/xxx`)
- *                                     → silently drop.
- *   3. `mention gating` — when `requireMention` is on, non-@bot messages
- *                         are `skip_no_mention`'d (still buffered to
- *                         history). Authorized control commands can
- *                         **bypass** the gate as long as the message does
- *                         not @anyone else at the same time.
- *   4. Otherwise → `pass` (the message will reach the AI pipeline).
- *
- * All inputs are plain data; there is no I/O and no mutation, so the
- * function is safe to share between the built-in and standalone builds.
- */
-
-// ────────────────────── Types ──────────────────────
-
-/**
- * Structured action returned by {@link resolveGroupMessageGate}.
- *
- * - `drop_other_mention`        — message @-s another user but not the bot;
- *                                 record to the group history cache and
- *                                 drop without hitting the AI.
- * - `block_unauthorized_command` — silently refuse a control command from
- *                                  an unauthorized sender (no history
- *                                  write, no AI call).
- * - `skip_no_mention`           — `requireMention` is on and the message
- *                                 does not @bot; record to history but
- *                                 skip AI dispatch.
- * - `pass`                      — forward the message to the AI pipeline.
- */
-type GroupMessageGateAction =
-  | "drop_other_mention"
-  | "block_unauthorized_command"
-  | "skip_no_mention"
-  | "pass";
-
-/** Gate evaluation result. */
-export interface GroupMessageGateResult {
-  /** The action the caller should take. */
-  action: GroupMessageGateAction;
-  /**
-   * Effective mention state after combining raw mention detection with
-   * implicit / bypass signals. Only meaningful when `action === "pass"`.
-   */
-  effectiveWasMentioned: boolean;
-  /**
-   * Whether the control-command bypass was applied to flip a missing
-   * mention into `pass`. Only meaningful when `action === "pass"`.
-   */
-  shouldBypassMention: boolean;
-}
-
-/** Input for {@link resolveGroupMessageGate}. */
-export interface GroupMessageGateInput {
-  // ---- ignoreOtherMentions layer ----
-  /** Per-group config: drop messages that @someone other than the bot. */
-  ignoreOtherMentions: boolean;
-  /** Whether the message contains *any* @mention (including @other-user). */
-  hasAnyMention: boolean;
-  /**
-   * Whether the QQ event explicitly @-s the bot (via `mentions[].is_you`
-   * or `GROUP_AT_MESSAGE_CREATE`).
-   */
-  wasMentioned: boolean;
-  /**
-   * Implicit mention — e.g. the message quotes an earlier bot reply.
-   * Treated as equivalent to an explicit @bot for gating purposes.
-   */
-  implicitMention: boolean;
-
-  // ---- Control-command layer ----
-  /** Whether text-based control commands are enabled globally. */
-  allowTextCommands: boolean;
-  /** Whether the current message is recognised as a control command. */
-  isControlCommand: boolean;
-  /** Whether the sender is authorised to run control commands. */
-  commandAuthorized: boolean;
-
-  // ---- Mention gating layer ----
-  /** Per-group config: `requireMention` — bot only replies when @-ed. */
-  requireMention: boolean;
-  /**
-   * Whether the channel can reliably detect @-mentions at all. In C2C chat
-   * this should be `false` (DMs don't have mentions); in group chat it
-   * should be `true`.
-   */
-  canDetectMention: boolean;
-}
-
-// ────────────────────── Core logic ──────────────────────
-
-/**
- * Base mention-gate evaluation.
- *
- * `effectiveWasMentioned = wasMentioned || implicitMention || bypass`.
- * `shouldSkip = requireMention && canDetectMention && !effectiveWasMentioned`.
- */
-function resolveMentionGating(input: {
-  requireMention: boolean;
-  canDetectMention: boolean;
-  wasMentioned: boolean;
-  implicitMention: boolean;
-  shouldBypassMention: boolean;
-}): { effectiveWasMentioned: boolean; shouldSkip: boolean } {
-  const effectiveWasMentioned =
-    input.wasMentioned || input.implicitMention || input.shouldBypassMention;
-  const shouldSkip = input.requireMention && input.canDetectMention && !effectiveWasMentioned;
-  return { effectiveWasMentioned, shouldSkip };
-}
-
-/**
- * Decide whether an authorized control command may bypass the mention gate.
- *
- * All of the following must hold:
- *   1. `requireMention` is on         (gate is active)
- *   2. The bot was NOT directly @-ed  (otherwise no bypass is needed)
- *   3. The message does NOT @anyone   (a `@other-user /stop` should NOT pass
- *                                      — the command wasn't aimed at us)
- *   4. Text commands are enabled
- *   5. Sender is authorised
- *   6. The content is a valid control command
- */
-function resolveCommandBypass(input: {
-  requireMention: boolean;
-  wasMentioned: boolean;
-  hasAnyMention: boolean;
-  allowTextCommands: boolean;
-  commandAuthorized: boolean;
-  isControlCommand: boolean;
-}): boolean {
-  return (
-    input.requireMention &&
-    !input.wasMentioned &&
-    !input.hasAnyMention &&
-    input.allowTextCommands &&
-    input.commandAuthorized &&
-    input.isControlCommand
-  );
-}
-
-// ────────────────────── Unified gate ──────────────────────
-
-/**
- * Evaluate the group-message gate.
- *
- * See the module-level docs for the ordering and semantics.
- */
-export function resolveGroupMessageGate(input: GroupMessageGateInput): GroupMessageGateResult {
-  // ---- Layer 1: ignoreOtherMentions ----
-  if (
-    input.ignoreOtherMentions &&
-    input.hasAnyMention &&
-    !input.wasMentioned &&
-    !input.implicitMention
-  ) {
-    return {
-      action: "drop_other_mention",
-      effectiveWasMentioned: false,
-      shouldBypassMention: false,
-    };
-  }
-
-  // ---- Layer 2: unauthorized control command ----
-  if (input.allowTextCommands && input.isControlCommand && !input.commandAuthorized) {
-    return {
-      action: "block_unauthorized_command",
-      effectiveWasMentioned: false,
-      shouldBypassMention: false,
-    };
-  }
-
-  // ---- Layer 3: mention gate + command bypass ----
-  const shouldBypassMention = resolveCommandBypass({
-    requireMention: input.requireMention,
-    wasMentioned: input.wasMentioned,
-    hasAnyMention: input.hasAnyMention,
-    allowTextCommands: input.allowTextCommands,
-    commandAuthorized: input.commandAuthorized,
-    isControlCommand: input.isControlCommand,
-  });
-
-  const mentionGate = resolveMentionGating({
-    requireMention: input.requireMention,
-    canDetectMention: input.canDetectMention,
-    wasMentioned: input.wasMentioned,
-    implicitMention: input.implicitMention,
-    shouldBypassMention,
-  });
-
-  if (mentionGate.shouldSkip) {
-    return {
-      action: "skip_no_mention",
-      effectiveWasMentioned: mentionGate.effectiveWasMentioned,
-      shouldBypassMention,
-    };
-  }
-
-  return {
-    action: "pass",
-    effectiveWasMentioned: mentionGate.effectiveWasMentioned,
-    shouldBypassMention,
-  };
-}

package/src/engine/messaging/decode-media-path.ts

@@ -1,82 +0,0 @@
-/**
- * Media path decoding utility.
- *
- * Extracted from `outbound-deliver.ts` — handles the `MEDIA:` prefix stripping,
- * tilde expansion, octal escape / UTF-8 byte-sequence decoding, and backslash
- * unescaping that media tags require.
- *
- * Zero external dependencies.
- */
-
-import type { EngineLogger } from "../types.js";
-
-/**
- * Normalize a file path by expanding `~` to the home directory and trimming.
- *
- * This is a minimal re-implementation of `utils/platform.ts#normalizePath`
- * so that `core/` remains self-contained.
- */
-function normalizePath(p: string): string {
-  let result = p.trim();
-  if (result.startsWith("~/") || result === "~") {
-    const home =
-      typeof process !== "undefined" ? (process.env.HOME ?? process.env.USERPROFILE) : undefined;
-    if (home) {
-      result = result === "~" ? home : `${home}${result.slice(1)}`;
-    }
-  }
-  return result;
-}
-
-/**
- * Decode a media path by stripping `MEDIA:`, expanding `~`, and unescaping
- * octal/UTF-8 byte sequences.
- *
- * @param raw - Raw path string from a media tag.
- * @param log - Optional logger for decode diagnostics.
- * @returns The decoded, normalized media path.
- */
-export function decodeMediaPath(raw: string, log?: EngineLogger): string {
-  let mediaPath = raw;
-  if (mediaPath.startsWith("MEDIA:")) {
-    mediaPath = mediaPath.slice("MEDIA:".length);
-  }
-  mediaPath = normalizePath(mediaPath);
-  mediaPath = mediaPath.replace(/\\\\/g, "\\");
-
-  // Skip octal escape decoding for Windows local paths (e.g. C:\Users\1\file.txt)
-  // where backslash-digit sequences like \1, \2 ... \7 are directory separators,
-  // not octal escape sequences.
-  const isWinLocal = /^[a-zA-Z]:[\\/]/.test(mediaPath) || mediaPath.startsWith("\\\\");
-  try {
-    const hasOctal = /\\[0-7]{1,3}/.test(mediaPath);
-    const hasNonASCII = /[\u0080-\u00FF]/.test(mediaPath);
-
-    if (!isWinLocal && (hasOctal || hasNonASCII)) {
-      log?.debug?.(`Decoding path with mixed encoding: ${mediaPath}`);
-      const decoded = mediaPath.replace(/\\([0-7]{1,3})/g, (_: string, octal: string) => {
-        return String.fromCharCode(Number.parseInt(octal, 8));
-      });
-      const bytes: number[] = [];
-      for (let i = 0; i < decoded.length; i++) {
-        const code = decoded.charCodeAt(i);
-        if (code <= 0xff) {
-          bytes.push(code);
-        } else {
-          const charBytes = Buffer.from(decoded[i], "utf8");
-          bytes.push(...charBytes);
-        }
-      }
-      const buffer = Buffer.from(bytes);
-      const utf8Decoded = buffer.toString("utf8");
-      if (!utf8Decoded.includes("\uFFFD") || utf8Decoded.length < decoded.length) {
-        mediaPath = utf8Decoded;
-        log?.debug?.(`Successfully decoded path: ${mediaPath}`);
-      }
-    }
-  } catch (decodeErr) {
-    log?.error(`Path decode error: ${String(decodeErr)}`);
-  }
-
-  return mediaPath;
-}

package/src/engine/messaging/media-source.ts

@@ -1,215 +0,0 @@
-/**
- * Unified media-source abstraction for the QQ Bot upload pipeline.
- *
- * All rich-media entry points (sender.ts#sendMedia, outbound.ts#send*,
- * reply-dispatcher.ts#handle*Payload) funnel through {@link normalizeSource}
- * before reaching the low-level {@link MediaApi}.
- *
- * ## Why four branches?
- *
- * - `url` — remote http(s) URL that the QQ server can fetch directly.
- * - `base64` — in-memory base64 string (typically from a `data:` URL).
- * - `localPath` — on-disk file; kept as a path so a future chunked-upload
- *   implementation can stream it via `fs.createReadStream` without the 4/3×
- *   base64 memory overhead.
- * - `buffer` — in-memory raw bytes (e.g. TTS output, downloaded url-fallback).
- *
- * ## Security baseline (localPath branch)
- *
- * `openLocalFile` is the single canonical implementation of "safely open a
- * local file for upload" across the plugin. It merges the previously
- * inconsistent strategies from `reply-dispatcher.ts` (O_NOFOLLOW + size check)
- * and `outbound.ts` (realpath + root containment). Callers are still
- * responsible for *root-whitelist* validation (via
- * `resolveQQBotPayloadLocalFilePath` / `resolveOutboundMediaPath`) before
- * passing the path in; this function enforces *file-level* safety only.
- *
- * Chunked upload is not implemented in this PR, but the contract here already
- * returns `size` metadata so `sendMediaInternal` can route by size without
- * reading the whole file first.
- */
-
-import * as fs from "node:fs";
-import { MAX_UPLOAD_SIZE, formatFileSize, getMimeType } from "../utils/file-utils.js";
-
-// ============ Types ============
-
-/**
- * Fully normalized media source. Downstream uploaders switch on `kind`.
- *
- * - `url`: remote URL — upload via `file_data=null; url=...`.
- * - `base64`: already-encoded base64 — upload via `file_data=...`.
- * - `localPath`: on-disk file — one-shot path reads it into a buffer;
- *   chunked path (future) streams it via `fs.createReadStream`.
- * - `buffer`: raw bytes in memory — same as above minus disk I/O.
- */
-export type MediaSource =
-  | { kind: "url"; url: string }
-  | { kind: "base64"; data: string; mime?: string }
-  | { kind: "localPath"; path: string; size: number; mime?: string }
-  | { kind: "buffer"; buffer: Buffer; fileName?: string; mime?: string };
-
-/**
- * Untyped media source accepted from callers.
- *
- * `url` may be either a remote `http(s)://...` URL or a `data:<mime>;base64,...`
- * data URL — {@link normalizeSource} transparently resolves the latter to a
- * `base64` branch.
- */
-export type RawMediaSource =
-  | { url: string }
-  | { base64: string; mime?: string }
-  | { localPath: string }
-  | { buffer: Buffer; fileName?: string; mime?: string };
-
-// ============ data: URL ============
-
-const DATA_URL_RE = /^data:([^;,]+);base64,(.+)$/i;
-
-/**
- * Parse a `data:<mime>;base64,<payload>` URL.
- *
- * Returns `null` when the string is not a data URL or does not declare
- * base64 encoding. Non-base64 data URLs are intentionally rejected because
- * the QQ upload API ingests raw base64, not arbitrary URL-encoded payloads.
- */
-function tryParseDataUrl(value: string): { mime: string; data: string } | null {
-  if (!value.startsWith("data:")) {
-    return null;
-  }
-  const m = value.match(DATA_URL_RE);
-  if (!m) {
-    return null;
-  }
-  return { mime: m[1], data: m[2] };
-}
-
-// ============ Local file safe open ============
-
-/**
- * Opened handle to a local file, with metadata already validated against
- * QQ upload limits.
- *
- * Callers MUST call {@link OpenedLocalFile.close} (typically in a `finally`).
- */
-interface OpenedLocalFile {
-  handle: fs.promises.FileHandle;
-  size: number;
-  close(): Promise<void>;
-}
-
-/**
- * Open a local file for upload with defense-in-depth:
- *
- * 1. `O_NOFOLLOW` refuses to traverse symlinks (prevents post-whitelist
- *    symlink swaps / TOCTOU attacks).
- * 2. `fstat` on the opened descriptor — NOT `fs.stat` on the path —
- *    so the size check applies to the exact byte stream we will read.
- * 3. Rejects non-regular files (sockets / devices / directories).
- * 4. Enforces a caller-specified `maxSize` (default {@link MAX_UPLOAD_SIZE})
- *    at open time, so oversized files fail fast without allocating a
- *    full buffer. Chunked upload callers should pass a larger ceiling
- *    (e.g. `CHUNKED_UPLOAD_MAX_SIZE` from `utils/file-utils.js`).
- *
- * The caller receives the open handle plus validated size and is expected
- * to either {@link OpenedLocalFile.handle.readFile} (one-shot path) or
- * stream via `fs.createReadStream` (chunked path).
- */
-export async function openLocalFile(
-  filePath: string,
-  opts: { maxSize?: number } = {},
-): Promise<OpenedLocalFile> {
-  const maxSize = opts.maxSize ?? MAX_UPLOAD_SIZE;
-  const openFlags =
-    fs.constants.O_RDONLY | ("O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0);
-  const handle = await fs.promises.open(filePath, openFlags);
-  try {
-    const stat = await handle.stat();
-    if (!stat.isFile()) {
-      throw new Error("Path is not a regular file");
-    }
-    if (stat.size > maxSize) {
-      throw new Error(
-        `File is too large (${formatFileSize(stat.size)}); QQ Bot API limit is ${formatFileSize(maxSize)}`,
-      );
-    }
-    return {
-      handle,
-      size: stat.size,
-      close: () => handle.close(),
-    };
-  } catch (err) {
-    // Close the handle on any validation failure to avoid fd leaks.
-    await handle.close().catch(() => undefined);
-    throw err;
-  }
-}
-
-// ============ Normalization ============
-
-/**
- * Normalize a {@link RawMediaSource} into a {@link MediaSource}.
- *
- * - Strings passed via `{ url }` that start with `data:` are auto-resolved
- *   to a `base64` branch (this is the unified `data:` URL support that was
- *   previously only implemented in `sendImage`).
- * - `localPath` branches open the file with {@link openLocalFile} solely to
- *   validate size / regular-file / O_NOFOLLOW invariants. The handle is
- *   closed immediately — actual reading is deferred to the uploader so
- *   the chunked path can stream without double-reading.
- * - `buffer` branches enforce the same ceiling inline.
- *
- * `maxSize` defaults to {@link MAX_UPLOAD_SIZE} (20MB, one-shot upload limit).
- * Callers that dispatch to the chunked uploader should pass a larger ceiling
- * (e.g. `CHUNKED_UPLOAD_MAX_SIZE`, or a value derived from
- * `getMaxUploadSize(fileType)`).
- *
- * NOTE: Root-whitelist validation (i.e. "this path must live under the
- * allowed QQ Bot media directory") is a caller concern. This function
- * assumes the path has already passed such checks.
- */
-export async function normalizeSource(
-  raw: RawMediaSource,
-  opts: { maxSize?: number } = {},
-): Promise<MediaSource> {
-  const maxSize = opts.maxSize ?? MAX_UPLOAD_SIZE;
-
-  if ("url" in raw) {
-    const parsed = tryParseDataUrl(raw.url);
-    if (parsed) {
-      return { kind: "base64", data: parsed.data, mime: parsed.mime };
-    }
-    return { kind: "url", url: raw.url };
-  }
-
-  if ("base64" in raw) {
-    return { kind: "base64", data: raw.base64, mime: raw.mime };
-  }
-
-  if ("localPath" in raw) {
-    const opened = await openLocalFile(raw.localPath, { maxSize });
-    try {
-      return {
-        kind: "localPath",
-        path: raw.localPath,
-        size: opened.size,
-        mime: getMimeType(raw.localPath),
-      };
-    } finally {
-      await opened.close();
-    }
-  }
-
-  // buffer branch
-  if (raw.buffer.length > maxSize) {
-    throw new Error(
-      `Buffer is too large (${formatFileSize(raw.buffer.length)}); QQ Bot API limit is ${formatFileSize(maxSize)}`,
-    );
-  }
-  return {
-    kind: "buffer",
-    buffer: raw.buffer,
-    fileName: raw.fileName,
-    mime: raw.mime,
-  };
-}