@tencent-connect/openclaw-qqbot 1.7.1 → 1.7.2

package/src/transport/webhook-transport.ts

@@ -0,0 +1,332 @@
+/**
+ * Webhook Transport — receive QQ Bot events via HTTP POST callbacks.
+ *
+ * Uses OpenClaw plugin-sdk's `registerWebhookTargetWithPluginRoute` (模式 C)
+ * to register webhook HTTP routes through the framework's gateway HTTP server,
+ * sharing the same port and benefiting from built-in rate limiting & in-flight guards.
+ *
+ * Architecture:
+ *   1. On gateway startAccount, register a webhook target via plugin-sdk
+ *   2. Framework routes POST requests to our handler
+ *   3. Handler verifies Ed25519 signatures and dispatches events
+ *   4. Returns op:12 ACK immediately, processes events asynchronously
+ *   5. On account stop (abortSignal), unregister the target
+ *
+ * Configuration (openclaw.yaml):
+ * ```yaml
+ * channels:
+ *   qqbot:
+ *     appId: "xxx"
+ *     clientSecret: "xxx"
+ *     transport: webhook
+ *     webhook:
+ *       path: /qqbot/webhook
+ * ```
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  registerWebhookTargetWithPluginRoute,
+  withResolvedWebhookRequestPipeline,
+  resolveWebhookTargetWithAuthOrRejectSync,
+  createWebhookInFlightLimiter,
+  createFixedWindowRateLimiter,
+  readWebhookBodyOrReject,
+  type WebhookInFlightLimiter,
+  type FixedWindowRateLimiter,
+} from "openclaw/plugin-sdk/webhook-ingress";
+
+import type { ResolvedQQBotAccount } from "../types.js";
+import { verifyWebhookSignature, signValidationResponse } from "./webhook-verify.js";
+
+// ============ Constants ============
+
+const OP_DISPATCH = 0;
+const OP_HTTP_CALLBACK_ACK = 12;
+const OP_VALIDATION = 13;
+
+const PLUGIN_ID = "openclaw-qqbot";
+const DEFAULT_WEBHOOK_PATH = "/qqbot/webhook";
+
+// ============ Types ============
+
+/** Webhook target registered per account */
+export interface QQBotWebhookTarget {
+  path: string;
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+}
+
+/** Webhook event dispatched to the consumer */
+export interface WebhookInboundEvent {
+  eventType: string;
+  data: unknown;
+  seq?: number;
+}
+
+/** Options for starting webhook transport */
+export interface WebhookTransportOptions {
+  account: ResolvedQQBotAccount;
+  abortSignal: AbortSignal;
+  onEvent: (event: WebhookInboundEvent) => void | Promise<void>;
+  onReady?: () => void;
+  onError?: (error: Error) => void;
+  log?: {
+    info: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error: (msg: string) => void;
+    debug?: (msg: string) => void;
+  };
+}
+
+// ============ Module state ============
+
+/** Per-path target registry (shared across all accounts) */
+const webhookTargets = new Map<string, QQBotWebhookTarget[]>();
+
+/** Per-account event handler map */
+const eventHandlers = new Map<string, (event: WebhookInboundEvent) => void | Promise<void>>();
+
+/** Module-level logger (set by the last startWebhookTransport call) */
+let log: WebhookTransportOptions["log"] | undefined;
+
+/** Shared rate limiter (fixed window, per source IP) */
+let rateLimiter: FixedWindowRateLimiter | null = null;
+
+/** Shared in-flight limiter */
+let inFlightLimiter: WebhookInFlightLimiter | null = null;
+
+function ensureGuards(): { rateLimiter: FixedWindowRateLimiter; inFlightLimiter: WebhookInFlightLimiter } {
+  if (!rateLimiter) {
+    rateLimiter = createFixedWindowRateLimiter({
+      windowMs: 60_000,
+      maxRequests: 600,
+      maxTrackedKeys: 4096,
+    });
+  }
+  if (!inFlightLimiter) {
+    inFlightLimiter = createWebhookInFlightLimiter({
+      maxInFlightPerKey: 8,
+      maxTrackedKeys: 4096,
+    });
+  }
+  return { rateLimiter, inFlightLimiter };
+}
+
+// ============ Main handler ============
+
+/**
+ * Shared HTTP handler for all QQBot webhook routes.
+ * Registered once per unique path, dispatches to the correct account target.
+ */
+async function handleQQBotWebhookRequest(req: IncomingMessage, res: ServerResponse): Promise<boolean | void> {
+  const guards = ensureGuards();
+
+  const handled = await withResolvedWebhookRequestPipeline({
+    req,
+    res,
+    targetsByPath: webhookTargets,
+    rateLimiter: guards.rateLimiter,
+    inFlightLimiter: guards.inFlightLimiter,
+    requireJsonContentType: true,
+    handle: async ({ targets }) => {
+      // Read raw body (up to 1MB, 30s timeout)
+      const bodyResult = await readWebhookBodyOrReject({
+        req,
+        res,
+        maxBytes: 1024 * 1024,
+        timeoutMs: 30_000,
+      });
+      if (!bodyResult.ok) return;
+
+      const rawBodyStr = bodyResult.value;
+      const rawBody = Buffer.from(rawBodyStr, "utf-8");
+      let payload: { op: number; d?: unknown; t?: string; s?: number };
+      try {
+        payload = JSON.parse(rawBodyStr);
+      } catch (err) {
+        log?.error(`[qqbot:webhook] Failed to parse request body as JSON: ${err instanceof Error ? err.message : String(err)}, body preview: ${rawBodyStr.slice(0, 200)}`);
+        res.statusCode = 400;
+        res.end(JSON.stringify({ error: "invalid json" }));
+        return;
+      }
+
+      // ── op:13 — Callback URL validation (before signature check) ──
+      if (payload.op === OP_VALIDATION) {
+        handleValidation(payload, targets, res);
+        return;
+      }
+
+      // ── Signature verification → resolve target ──
+      const timestamp = getHeader(req, "x-signature-timestamp") ?? "";
+      const signature = getHeader(req, "x-signature-ed25519") ?? "";
+
+      if (!timestamp || !signature) {
+        log?.warn?.(`[qqbot:webhook] Missing signature headers — timestamp: "${timestamp}", signature: "${signature}", url: ${req.url}`);
+        res.statusCode = 401;
+        res.end(JSON.stringify({ error: "missing signature headers" }));
+        return;
+      }
+
+      const matchedTarget = resolveWebhookTargetWithAuthOrRejectSync({
+        targets,
+        res,
+        isMatch: (target) =>
+          verifyWebhookSignature({
+            body: rawBody,
+            timestamp,
+            signature,
+            botSecret: target.clientSecret,
+          }),
+        unauthorizedStatusCode: 401,
+        unauthorizedMessage: JSON.stringify({ error: "invalid signature" }),
+      });
+
+      if (!matchedTarget) {
+        log?.warn?.(`[qqbot:webhook] Signature verification failed for path: ${req.url}, timestamp: ${timestamp}`);
+        return; // response already sent by resolver
+      }
+
+      // ── ACK immediately ──
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ op: OP_HTTP_CALLBACK_ACK, d: 0 }));
+
+      // ── Async dispatch (fire-and-forget) ──
+      if (payload.op === OP_DISPATCH) {
+        const handler = eventHandlers.get(matchedTarget.accountId);
+        if (handler) {
+          Promise.resolve(
+            handler({
+              eventType: payload.t ?? "",
+              data: payload.d,
+              seq: payload.s,
+            }),
+          ).catch((err) => {
+            log?.error(`[qqbot:${matchedTarget.accountId}] Event handler error for "${payload.t}": ${err instanceof Error ? err.message : String(err)}`);
+          });
+        } else {
+          log?.warn?.(`[qqbot:webhook] No event handler registered for account: ${matchedTarget.accountId}, event: ${payload.t}`);
+        }
+      }
+    },
+  });
+
+  return handled;
+}
+
+// ============ Validation handler (op:13) ============
+
+function handleValidation(
+  payload: { d?: unknown },
+  targets: QQBotWebhookTarget[],
+  res: ServerResponse,
+): void {
+  const d = payload.d as { plain_token?: string; event_ts?: string } | undefined;
+
+  if (!d?.plain_token || !d?.event_ts) {
+    log?.warn?.(`[qqbot:webhook] Invalid validation payload (op:13): missing plain_token or event_ts, got: ${JSON.stringify(d)}`);
+    res.statusCode = 400;
+    res.end(JSON.stringify({ error: "invalid validation payload" }));
+    return;
+  }
+
+  // Use the first target's secret for validation
+  // (op:13 is sent during URL registration, only one bot should be using the path at that time)
+  const target = targets[0];
+  if (!target) {
+    log?.error(`[qqbot:webhook] No target registered for validation (op:13), cannot sign response`);
+    res.statusCode = 500;
+    res.end(JSON.stringify({ error: "no target registered" }));
+    return;
+  }
+
+  const response = signValidationResponse({
+    plainToken: d.plain_token,
+    eventTs: d.event_ts,
+    botSecret: target.clientSecret,
+  });
+
+  res.statusCode = 200;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(response));
+}
+
+// ============ Public API ============
+
+/**
+ * Start the webhook transport for a given account.
+ *
+ * Registers a webhook target on the framework's plugin HTTP route system.
+ * The handler verifies Ed25519 signatures, ACKs immediately, and dispatches
+ * events asynchronously via the provided `onEvent` callback.
+ *
+ * Returns when the abortSignal is triggered (account stopped).
+ */
+export async function startWebhookTransport(opts: WebhookTransportOptions): Promise<void> {
+  const { account, abortSignal, onEvent, onReady, onError, log: optLog } = opts;
+  log = optLog;
+  const webhookPath = account.config.webhook?.path ?? DEFAULT_WEBHOOK_PATH;
+
+  log?.info(`[qqbot:${account.accountId}] Starting webhook transport on path: ${webhookPath}`);
+
+  // Register event handler for this account
+  eventHandlers.set(account.accountId, onEvent);
+
+  // Register webhook target + plugin HTTP route
+  const { unregister } = registerWebhookTargetWithPluginRoute({
+    targetsByPath: webhookTargets,
+    target: {
+      path: webhookPath,
+      accountId: account.accountId,
+      appId: account.appId,
+      clientSecret: account.clientSecret,
+    },
+    route: {
+      auth: "plugin",
+      match: "exact" as const,
+      pluginId: PLUGIN_ID,
+      source: "qqbot-webhook",
+      accountId: account.accountId,
+      replaceExisting: true,
+      log: (msg: string) => log?.info(msg),
+      handler: handleQQBotWebhookRequest,
+    },
+    onLastPathTargetRemoved: () => {
+      log?.info(`[qqbot] Last webhook target removed from path: ${webhookPath}`);
+    },
+  });
+
+  log?.info(`[qqbot:${account.accountId}] Webhook transport registered on path: ${webhookPath}`);
+  onReady?.();
+
+  // Wait until abort signal fires
+  await new Promise<void>((resolve) => {
+    if (abortSignal.aborted) {
+      resolve();
+      return;
+    }
+    abortSignal.addEventListener("abort", () => resolve(), { once: true });
+  });
+
+  // Cleanup
+  unregister();
+  eventHandlers.delete(account.accountId);
+  log?.info(`[qqbot:${account.accountId}] Webhook transport stopped`);
+}
+
+/**
+ * Resolve the webhook path for a given account (for external configuration / setWebhook calls).
+ */
+export function resolveWebhookPath(account: ResolvedQQBotAccount): string {
+  return account.config.webhook?.path ?? DEFAULT_WEBHOOK_PATH;
+}
+
+// ============ Helpers ============
+
+function getHeader(req: IncomingMessage, key: string): string | undefined {
+  const val = req.headers[key];
+  if (Array.isArray(val)) return val[0];
+  return val;
+}

package/src/transport/webhook-verify.ts

@@ -0,0 +1,119 @@
+/**
+ * Webhook signature verification — Ed25519.
+ *
+ * QQ Open Platform uses Ed25519 for webhook callback verification:
+ *   1. Bot secret is padded/truncated to 32 bytes as the Ed25519 seed.
+ *   2. The public key verifies `timestamp + body` against `X-Signature-Ed25519`.
+ *   3. For callback URL validation (op:13), signs `event_ts + plain_token`.
+ *
+ * Reference: https://bot.q.qq.com/wiki/develop/api-v2/dev-prepare/interface-framework/event-emit.html
+ */
+
+import * as crypto from "node:crypto";
+
+// ============ Seed derivation ============
+
+/**
+ * Derive an Ed25519 seed (32 bytes) from the bot secret.
+ * QQ's spec: repeat the secret until >= 32 chars, then truncate to 32.
+ */
+function deriveSeed(botSecret: string): Buffer {
+  let seed = botSecret;
+  while (seed.length < 32) {
+    seed = seed + seed;
+  }
+  return Buffer.from(seed.slice(0, 32), "utf-8");
+}
+
+/**
+ * Generate Ed25519 key pair from bot secret.
+ */
+function getKeyPair(botSecret: string): { privateKey: crypto.KeyObject; publicKey: crypto.KeyObject } {
+  const seed = deriveSeed(botSecret);
+  // Node.js Ed25519: create private key from raw 32-byte seed
+  const privateKey = crypto.createPrivateKey({
+    key: Buffer.concat([
+      // Ed25519 PKCS8 DER prefix for 32-byte seed
+      Buffer.from("302e020100300506032b657004220420", "hex"),
+      seed,
+    ]),
+    format: "der",
+    type: "pkcs8",
+  });
+  const publicKey = crypto.createPublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+
+// ============ Signature generation ============
+
+/**
+ * Sign a message using the bot's Ed25519 private key.
+ * Returns hex-encoded signature.
+ */
+export function ed25519Sign(botSecret: string, message: Buffer): string {
+  const { privateKey } = getKeyPair(botSecret);
+  const signature = crypto.sign(null, message, privateKey);
+  return signature.toString("hex");
+}
+
+// ============ Signature verification ============
+
+/**
+ * Verify an Ed25519 signature from a QQ webhook callback request.
+ *
+ * @param params.body - Raw request body (Buffer)
+ * @param params.timestamp - Value of `X-Signature-Timestamp` header
+ * @param params.signature - Value of `X-Signature-Ed25519` header (hex string)
+ * @param params.botSecret - The bot's AppSecret
+ * @returns `true` if signature is valid
+ */
+export function verifyWebhookSignature(params: {
+  body: Buffer;
+  timestamp: string;
+  signature: string;
+  botSecret: string;
+}): boolean {
+  const { body, timestamp, signature, botSecret } = params;
+
+  try {
+    const { publicKey } = getKeyPair(botSecret);
+    const message = Buffer.concat([
+      Buffer.from(timestamp, "utf-8"),
+      body,
+    ]);
+    const sigBuffer = Buffer.from(signature, "hex");
+    return crypto.verify(null, message, publicKey, sigBuffer);
+  } catch (err) {
+    console.warn(`[qqbot:webhook-verify] Ed25519 verification threw: ${err instanceof Error ? err.message : String(err)}`);
+    return false;
+  }
+}
+
+// ============ Callback URL validation (op:13) ============
+
+/**
+ * Generate the response for callback URL validation (op:13).
+ *
+ * QQ sends `{ op: 13, d: { plain_token, event_ts } }` to verify
+ * the callback URL. We must return `{ plain_token, signature }`.
+ *
+ * @param params.plainToken - The `plain_token` from the validation request
+ * @param params.eventTs - The `event_ts` from the validation request
+ * @param params.botSecret - The bot's AppSecret
+ */
+export function signValidationResponse(params: {
+  plainToken: string;
+  eventTs: string;
+  botSecret: string;
+}): { plain_token: string; signature: string } {
+  const { plainToken, eventTs, botSecret } = params;
+
+  // Sign: event_ts + plain_token
+  const message = Buffer.from(eventTs + plainToken, "utf-8");
+  const signature = ed25519Sign(botSecret, message);
+
+  return {
+    plain_token: plainToken,
+    signature,
+  };
+}

package/src/types.ts

@@ -29,6 +29,8 @@ export interface ResolvedQQBotAccount {
   imageServerBaseUrl?: string;
   /** 是否支持 markdown 消息（默认 true） */
   markdownSupport: boolean;
+  /** User-Agent 追加后缀（从通道级配置 channels.qqbot.userAgentSuffix 解析） */
+  userAgentSuffix?: string;
   config: QQBotAccountConfig;
 }
 
@@ -57,6 +59,15 @@ export interface GroupConfig {
   historyLimit?: number;
 }
 
+/** 消息接收传输方式 */
+export type TransportMode = "websocket" | "webhook";
+
+/** Webhook 传输配置 */
+export interface WebhookTransportConfig {
+  /** 监听路径（默认 /qqbot/webhook） */
+  path?: string;
+}
+
 /**
  * QQ Bot 账户配置
  */
@@ -68,6 +79,10 @@ export interface QQBotAccountConfig {
   clientSecretFile?: string;
   dmPolicy?: "open" | "pairing" | "allowlist";
   allowFrom?: string[];
+  /** 消息接收传输方式：websocket（默认）| webhook */
+  transport?: TransportMode;
+  /** webhook 传输配置（transport="webhook" 时生效） */
+  webhook?: WebhookTransportConfig;
   /** 群消息策略（默认 allowlist） */
   groupPolicy?: GroupPolicy;
   /** 群白名单（groupPolicy 为 allowlist 时生效） */
@@ -114,6 +129,12 @@ export interface QQBotAccountConfig {
    * 示例: "ryantest/openclaw-qqbot"
    */
   upgradePkg?: string;
+  /**
+   * 群消息是否默认需要 @机器人才响应（默认 true）
+   * 优先级低于 groups.{groupId}.requireMention 和 groups."*".requireMention
+   * 设为 false 时，所有群默认无需 @ 即触发回复（仍可被群级配置覆盖）
+   */
+  defaultRequireMention?: boolean;
   /**
    * 出站消息合并回复（debounce）配置
    * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸
@@ -124,7 +145,7 @@ export interface QQBotAccountConfig {
    * 启用后，AI 的回复会以流式形式逐步显示在 QQ 聊天中，
    * 用户可以看到文字逐字出现的打字机效果。
    * 设置为 true 可开启流式消息。
-   * 
+   *
    * 注意：仅 C2C（私聊）支持流式消息 API。
    */
   streaming?: boolean;

package/src/typings/openclaw-webhook-ingress.d.ts

@@ -0,0 +1,66 @@
+declare module "openclaw/plugin-sdk/webhook-ingress" {
+  import type { IncomingMessage, ServerResponse } from "node:http";
+
+  export interface WebhookInFlightLimiter {
+    acquire(): boolean;
+    release(): void;
+  }
+
+  export interface FixedWindowRateLimiter {
+    check(key?: string): boolean;
+  }
+
+  export function createWebhookInFlightLimiter(opts: {
+    max?: number;
+    maxInFlightPerKey?: number;
+    maxTrackedKeys?: number;
+  }): WebhookInFlightLimiter;
+
+  export function createFixedWindowRateLimiter(opts: {
+    windowMs: number;
+    max?: number;
+    maxRequests?: number;
+    maxTrackedKeys?: number;
+  }): FixedWindowRateLimiter;
+
+  export function registerWebhookTargetWithPluginRoute<T extends { path: string }>(opts: {
+    targetsByPath: Map<string, T[]>;
+    target: T;
+    route: {
+      auth: string;
+      match: "exact" | "prefix";
+      pluginId: string;
+      source: string;
+      accountId: string;
+      replaceExisting?: boolean;
+      log?: (msg: string) => void;
+      handler: (req: IncomingMessage, res: ServerResponse) => Promise<boolean | void>;
+    };
+    onLastPathTargetRemoved?: () => void;
+  }): { unregister: () => void };
+
+  export function withResolvedWebhookRequestPipeline<T extends { path: string }>(opts: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    targetsByPath: Map<string, T[]>;
+    rateLimiter: FixedWindowRateLimiter;
+    inFlightLimiter: WebhookInFlightLimiter;
+    requireJsonContentType?: boolean;
+    handle: (ctx: { targets: T[] }) => Promise<void> | void;
+  }): Promise<boolean>;
+
+  export function resolveWebhookTargetWithAuthOrRejectSync<T>(opts: {
+    targets: T[];
+    res: ServerResponse;
+    isMatch: (target: T) => boolean;
+    unauthorizedStatusCode?: number;
+    unauthorizedMessage?: string;
+  }): T | null;
+
+  export function readWebhookBodyOrReject(opts: {
+    req: IncomingMessage;
+    res: ServerResponse;
+    maxBytes: number;
+    timeoutMs: number;
+  }): Promise<{ ok: true; value: string } | { ok: false }>;
+}

package/src/utils/audio-convert.ts

@@ -1,9 +1,30 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFile } from "node:child_process";
-import { decode, encode, isSilk } from "silk-wasm";
 import { detectFfmpeg, isWindows } from "./platform.js";
 
+// silk-wasm 动态加载（可选依赖，未安装时降级为不支持语音编解码）
+let silkWasm: { decode: typeof import("silk-wasm").decode; encode: typeof import("silk-wasm").encode; isSilk: typeof import("silk-wasm").isSilk } | null = null;
+let silkWasmLoaded = false;
+
+async function loadSilkWasm() {
+  if (silkWasmLoaded) return silkWasm;
+  silkWasmLoaded = true;
+  try {
+    silkWasm = await import("silk-wasm");
+  } catch {
+    console.warn("[audio-convert] silk-wasm not available, voice encoding/decoding disabled");
+    silkWasm = null;
+  }
+  return silkWasm;
+}
+
+// 同步版本的 isSilk（用于不方便 await 的场景），首次调用前需先 loadSilkWasm
+function isSilkSync(data: Uint8Array): boolean {
+  if (!silkWasm) return false;
+  return silkWasm.isSilk(data);
+}
+
 /**
  * 检查文件是否为 SILK 格式（QQ/微信语音常用格式）
  * QQ 语音文件通常以 .amr 扩展名保存，但实际编码可能是 SILK v3
@@ -12,7 +33,7 @@ import { detectFfmpeg, isWindows } from "./platform.js";
 function isSilkFile(filePath: string): boolean {
   try {
     const buf = fs.readFileSync(filePath);
-    return isSilk(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
+    return isSilkSync(new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength));
   } catch {
     return false;
   }
@@ -91,14 +112,15 @@ export async function convertSilkToWav(
   const rawData = new Uint8Array(strippedBuf.buffer, strippedBuf.byteOffset, strippedBuf.byteLength);
 
   // 验证是否为 SILK 格式
-  if (!isSilk(rawData)) {
+  const silk = await loadSilkWasm();
+  if (!silk || !silk.isSilk(rawData)) {
     return null;
   }
 
   // SILK 解码为 PCM (s16le)
   // QQ 语音通常采样率为 24000Hz
   const sampleRate = 24000;
-  const result = await decode(rawData, sampleRate);
+  const result = await silk.decode(rawData, sampleRate);
 
   // PCM → WAV
   const wavBuffer = pcmToWav(result.data, sampleRate);
@@ -380,8 +402,12 @@ export async function pcmToSilk(
   pcmBuffer: Buffer,
   sampleRate: number,
 ): Promise<{ silkBuffer: Buffer; duration: number }> {
+  const silk = await loadSilkWasm();
+  if (!silk) {
+    throw new Error("silk-wasm not available, cannot encode PCM to SILK. Install silk-wasm to enable voice sending.");
+  }
   const pcmData = new Uint8Array(pcmBuffer.buffer, pcmBuffer.byteOffset, pcmBuffer.byteLength);
-  const result = await encode(pcmData, sampleRate);
+  const result = await silk.encode(pcmData, sampleRate);
   return {
     silkBuffer: Buffer.from(result.data.buffer, result.data.byteOffset, result.data.byteLength),
     duration: result.duration,
@@ -440,10 +466,11 @@ export async function audioFileToSilkBase64(filePath: string, directUploadFormat
   }
 
   // 1. .slk / .amr 扩展名 → 检测 SILK 魔数，是 SILK 则直传
+  const silk = await loadSilkWasm();
   if ([".slk", ".slac"].includes(ext)) {
     const stripped = stripAmrHeader(buf);
     const raw = new Uint8Array(stripped.buffer, stripped.byteOffset, stripped.byteLength);
-    if (isSilk(raw)) {
+    if (silk?.isSilk(raw)) {
       console.log(`[audio-convert] SILK file, direct use: ${filePath} (${buf.length} bytes)`);
       return buf.toString("base64");
     }
@@ -453,7 +480,7 @@ export async function audioFileToSilkBase64(filePath: string, directUploadFormat
   const rawCheck = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   const strippedCheck = stripAmrHeader(buf);
   const strippedRaw = new Uint8Array(strippedCheck.buffer, strippedCheck.byteOffset, strippedCheck.byteLength);
-  if (isSilk(rawCheck) || isSilk(strippedRaw)) {
+  if (silk?.isSilk(rawCheck) || silk?.isSilk(strippedRaw)) {
     console.log(`[audio-convert] SILK detected by header: ${filePath} (${buf.length} bytes)`);
     return buf.toString("base64");
   }
@@ -544,10 +571,11 @@ export async function audioFileToSilkFile(filePath: string, directUploadFormats?
   }
 
   // 1. 已经是 SILK 编码 → 直接返回原文件
+  const silk = await loadSilkWasm();
   if ([".slk", ".slac"].includes(ext)) {
     const stripped = stripAmrHeader(buf);
     const raw = new Uint8Array(stripped.buffer, stripped.byteOffset, stripped.byteLength);
-    if (isSilk(raw)) {
+    if (silk?.isSilk(raw)) {
       console.log(`[audio-convert] SILK file, direct use: ${filePath} (${buf.length} bytes)`);
       return filePath;
     }
@@ -555,7 +583,7 @@ export async function audioFileToSilkFile(filePath: string, directUploadFormats?
   const rawCheck = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
   const strippedCheck = stripAmrHeader(buf);
   const strippedRaw = new Uint8Array(strippedCheck.buffer, strippedCheck.byteOffset, strippedCheck.byteLength);
-  if (isSilk(rawCheck) || isSilk(strippedRaw)) {
+  if (silk?.isSilk(rawCheck) || silk?.isSilk(strippedRaw)) {
     console.log(`[audio-convert] SILK detected by header: ${filePath} (${buf.length} bytes)`);
     return filePath;
   }