@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/src/stt.ts

@@ -1,86 +0,0 @@
-/**
- * 通用 OpenAI 兼容 STT（语音转文字）
- *
- * 为什么在插件侧做 STT 而不走框架管道？
- * 框架的 applyMediaUnderstanding 同时执行 runCapability("audio") 和 extractFileBlocks。
- * 后者会把 WAV 文件的 PCM 二进制当文本注入 Body（looksLikeUtf8Text 误判），导致 context 爆炸。
- * 在插件侧完成 STT 后不把 WAV 放入 MediaPaths，即可规避此框架 bug。
- *
- * 配置解析策略（与 TTS 统一的两级回退）：
- * 1. 优先 channels.qqbot.stt（插件专属配置）
- * 2. 回退 tools.media.audio.models[0]（框架级配置）
- * 3. 再从 models.providers.[provider] 继承 apiKey/baseUrl
- * 4. 支持任何 OpenAI 兼容的 STT 服务
- */
-
-import * as fs from "node:fs";
-import path from "node:path";
-import { sanitizeFileName } from "./utils/platform.js";
-
-export interface STTConfig {
-  baseUrl: string;
-  apiKey: string;
-  model: string;
-}
-
-export function resolveSTTConfig(cfg: Record<string, unknown>): STTConfig | null {
-  const c = cfg as any;
-
-  // 优先使用 channels.qqbot.stt（插件专属配置）
-  const channelStt = c?.channels?.qqbot?.stt;
-  if (channelStt && channelStt.enabled !== false) {
-    const providerId: string = channelStt?.provider || "openai";
-    const providerCfg = c?.models?.providers?.[providerId];
-    const baseUrl: string | undefined = channelStt?.baseUrl || providerCfg?.baseUrl;
-    const apiKey: string | undefined = channelStt?.apiKey || providerCfg?.apiKey;
-    const model: string = channelStt?.model || "whisper-1";
-    if (baseUrl && apiKey) {
-      return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
-    }
-  }
-
-  // 回退到 tools.media.audio.models[0]（框架级配置）
-  const audioModelEntry = c?.tools?.media?.audio?.models?.[0];
-  if (audioModelEntry) {
-    const providerId: string = audioModelEntry?.provider || "openai";
-    const providerCfg = c?.models?.providers?.[providerId];
-    const baseUrl: string | undefined = audioModelEntry?.baseUrl || providerCfg?.baseUrl;
-    const apiKey: string | undefined = audioModelEntry?.apiKey || providerCfg?.apiKey;
-    const model: string = audioModelEntry?.model || "whisper-1";
-    if (baseUrl && apiKey) {
-      return { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey, model };
-    }
-  }
-
-  return null;
-}
-
-export async function transcribeAudio(audioPath: string, cfg: Record<string, unknown>): Promise<string | null> {
-  const sttCfg = resolveSTTConfig(cfg);
-  if (!sttCfg) return null;
-
-  const fileBuffer = fs.readFileSync(audioPath);
-  const fileName = sanitizeFileName(path.basename(audioPath));
-  const mime = fileName.endsWith(".wav") ? "audio/wav"
-    : fileName.endsWith(".mp3") ? "audio/mpeg"
-    : fileName.endsWith(".ogg") ? "audio/ogg"
-    : "application/octet-stream";
-
-  const form = new FormData();
-  form.append("file", new Blob([fileBuffer], { type: mime }), fileName);
-  form.append("model", sttCfg.model);
-
-  const resp = await fetch(`${sttCfg.baseUrl}/audio/transcriptions`, {
-    method: "POST",
-    headers: { "Authorization": `Bearer ${sttCfg.apiKey}` },
-    body: form,
-  });
-
-  if (!resp.ok) {
-    const detail = await resp.text().catch(() => "");
-    throw new Error(`STT failed (HTTP ${resp.status}): ${detail.slice(0, 300)}`);
-  }
-
-  const result = await resp.json() as { text?: string };
-  return result.text?.trim() || null;
-}

package/src/tools/channel.ts

@@ -1,275 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { resolveQQBotAccount } from "../config.js";
-import { listQQBotAccountIds } from "../config.js";
-import { getAccessToken, API_BASE } from "../api.js";
-
-const DEFAULT_TIMEOUT_MS = 30000;
-
-// ========== 类型定义 ==========
-
-interface ChannelApiParams {
-  method: string;
-  path: string;
-  body?: Record<string, unknown>;
-  query?: Record<string, string>;
-}
-
-// ========== JSON Schema ==========
-
-const ChannelApiSchema = {
-  type: "object",
-  properties: {
-    method: {
-      type: "string",
-      description:
-        "HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE",
-      enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
-    },
-    path: {
-      type: "string",
-      description:
-        "API 路径（不含域名），占位符需替换为实际值。" +
-        "示例：/users/@me/guilds, /guilds/{guild_id}/channels, /channels/{channel_id}",
-    },
-    body: {
-      type: "object",
-      description:
-        "请求体（JSON），用于 POST/PUT/PATCH 请求。" +
-        "GET/DELETE 请求不需要此参数。",
-    },
-    query: {
-      type: "object",
-      description:
-        "URL 查询参数（键值对），会拼接到路径后面。" +
-        "如 { \"limit\": \"100\", \"after\": \"0\" } 会拼接为 ?limit=100&after=0",
-      additionalProperties: { type: "string" },
-    },
-  },
-  required: ["method", "path"],
-} as const;
-
-// ========== 工具函数 ==========
-
-function json(data: unknown) {
-  return {
-    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
-    details: data,
-  };
-}
-
-/**
- * 构建完整的请求 URL
- */
-function buildUrl(path: string, query?: Record<string, string>): string {
-  let url = `${API_BASE}${path}`;
-  if (query && Object.keys(query).length > 0) {
-    const params = new URLSearchParams();
-    for (const [key, value] of Object.entries(query)) {
-      if (value !== undefined && value !== null && value !== "") {
-        params.set(key, value);
-      }
-    }
-    const qs = params.toString();
-    if (qs) {
-      url += `?${qs}`;
-    }
-  }
-  return url;
-}
-
-/**
- * 校验 path 防止 SSRF
- */
-function validatePath(path: string): string | null {
-  if (!path.startsWith("/")) {
-    return "path 必须以 / 开头";
-  }
-  if (path.includes("..") || path.includes("//")) {
-    return "path 不允许包含 .. 或 //";
-  }
-  // 只允许合法的 URL path 字符
-  if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") {
-    return "path 包含非法字符";
-  }
-  return null;
-}
-
-// ========== 注册入口 ==========
-
-/**
- * 注册 QQ 频道 API 代理工具。
- *
- * 该工具作为 QQ 开放平台频道 API 的 HTTP 代理，自动处理 Token 鉴权。
- * AI 通过 skill 文档了解各接口的路径、方法和参数，构造请求后由此工具代理发送。
- *
- * 支持的能力：
- * - 频道管理（Guild）
- * - 子频道管理（Channel）
- * - 成员管理（Member）
- * - 公告管理（Announces）
- * - 论坛管理（Forum Thread）
- * - 日程管理（Schedule）
- */
-export function registerChannelTool(api: OpenClawPluginApi): void {
-  const cfg = api.config;
-  if (!cfg) {
-    console.log("[qqbot-channel-api] No config available, skipping");
-    return;
-  }
-
-  const accountIds = listQQBotAccountIds(cfg);
-  if (accountIds.length === 0) {
-    console.log("[qqbot-channel-api] No QQBot accounts configured, skipping");
-    return;
-  }
-
-  const firstAccountId = accountIds[0];
-  const account = resolveQQBotAccount(cfg, firstAccountId);
-
-  if (!account.appId || !account.clientSecret) {
-    console.log("[qqbot-channel-api] Account not fully configured, skipping");
-    return;
-  }
-
-  api.registerTool(
-    {
-      name: "qqbot_channel_api",
-      label: "QQBot Channel API",
-      description:
-        "QQ 开放平台频道 API HTTP 代理，自动填充鉴权 Token。" +
-        "常用接口速查：" +
-        "频道列表 GET /users/@me/guilds | " +
-        "子频道列表 GET /guilds/{guild_id}/channels | " +
-        "子频道详情 GET /channels/{channel_id} | " +
-        "创建子频道 POST /guilds/{guild_id}/channels | " +
-        "成员列表 GET /guilds/{guild_id}/members?after=0&limit=100 | " +
-        "成员详情 GET /guilds/{guild_id}/members/{user_id} | " +
-        "帖子列表 GET /channels/{channel_id}/threads | " +
-        "发帖 PUT /channels/{channel_id}/threads | " +
-        "创建公告 POST /guilds/{guild_id}/announces | " +
-        "创建日程 POST /channels/{channel_id}/schedules。" +
-        "更多接口和参数详情请阅读 qqbot-channel skill。",
-      parameters: ChannelApiSchema,
-      async execute(_toolCallId, params) {
-        const p = params as ChannelApiParams;
-
-        // 参数校验
-        if (!p.method) {
-          return json({ error: "method 为必填参数" });
-        }
-        if (!p.path) {
-          return json({ error: "path 为必填参数" });
-        }
-
-        const method = p.method.toUpperCase();
-        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
-          return json({ error: `不支持的 HTTP 方法: ${method}，可选值：GET, POST, PUT, PATCH, DELETE` });
-        }
-
-        // 路径安全校验
-        const pathError = validatePath(p.path);
-        if (pathError) {
-          return json({ error: pathError });
-        }
-
-        // GET/DELETE 不应有 body
-        if ((method === "GET" || method === "DELETE") && p.body && Object.keys(p.body).length > 0) {
-          console.log(`[qqbot-channel-api] ${method} request with body, body will be ignored`);
-        }
-
-        try {
-          // 获取鉴权 Token
-          const accessToken = await getAccessToken(account.appId, account.clientSecret);
-
-          // 构建请求
-          const url = buildUrl(p.path, p.query);
-          const headers: Record<string, string> = {
-            Authorization: `QQBot ${accessToken}`,
-            "Content-Type": "application/json",
-          };
-
-          const controller = new AbortController();
-          const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
-
-          const fetchOptions: RequestInit = {
-            method,
-            headers,
-            signal: controller.signal,
-          };
-
-          // POST/PUT/PATCH 才发送 body
-          if (p.body && ["POST", "PUT", "PATCH"].includes(method)) {
-            fetchOptions.body = JSON.stringify(p.body);
-          }
-
-          console.log(`[qqbot-channel-api] >>> ${method} ${url} (timeout: ${DEFAULT_TIMEOUT_MS}ms)`);
-
-          let res: Response;
-          try {
-            res = await fetch(url, fetchOptions);
-          } catch (err) {
-            clearTimeout(timeoutId);
-            if (err instanceof Error && err.name === "AbortError") {
-              console.error(`[qqbot-channel-api] <<< Request timeout after ${DEFAULT_TIMEOUT_MS}ms`);
-              return json({ error: `请求超时（${DEFAULT_TIMEOUT_MS}ms）`, path: p.path });
-            }
-            console.error(`[qqbot-channel-api] <<< Network error:`, err);
-            return json({
-              error: `网络错误: ${err instanceof Error ? err.message : String(err)}`,
-              path: p.path,
-            });
-          } finally {
-            clearTimeout(timeoutId);
-          }
-
-          console.log(`[qqbot-channel-api] <<< Status: ${res.status} ${res.statusText}`);
-
-          // 解析响应
-          const rawBody = await res.text();
-
-          // 空响应（如 DELETE 204）
-          if (!rawBody || rawBody.trim() === "") {
-            if (res.ok) {
-              return json({ success: true, status: res.status, path: p.path });
-            }
-            return json({
-              error: `API 返回 ${res.status} ${res.statusText}`,
-              status: res.status,
-              path: p.path,
-            });
-          }
-
-          let data: unknown;
-          try {
-            data = JSON.parse(rawBody);
-          } catch {
-            return json({
-              error: "响应解析失败",
-              status: res.status,
-              raw: rawBody.slice(0, 500),
-              path: p.path,
-            });
-          }
-
-          if (!res.ok) {
-            const errData = data as { message?: string; code?: number };
-            return json({
-              error: errData.message ?? `API 错误 (HTTP ${res.status})`,
-              code: errData.code,
-              status: res.status,
-              path: p.path,
-              detail: data,
-            });
-          }
-
-          return json(data);
-        } catch (err) {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          console.error(`[qqbot-channel-api] Error [${method} ${p.path}]: ${errMsg}`);
-          return json({ error: errMsg, path: p.path });
-        }
-      },
-    },
-    { name: "qqbot_channel_api" },
-  );
-}

package/src/transport/index.ts

@@ -1,11 +0,0 @@
-/**
- * Transport module — QQ Bot event receiving mechanisms.
- *
- * Supports two transport modes:
- *   - **WebSocket** (default): long-lived WS connection with heartbeat, RESUME, etc.
- *   - **Webhook** (HTTP callback): QQ platform POSTs events to registered path.
- */
-
-export type { WebhookInboundEvent, WebhookTransportOptions, QQBotWebhookTarget } from "./webhook-transport.js";
-export { startWebhookTransport, resolveWebhookPath } from "./webhook-transport.js";
-export { verifyWebhookSignature, signValidationResponse, ed25519Sign } from "./webhook-verify.js";

package/src/transport/webhook-transport.ts

@@ -1,332 +0,0 @@
-/**
- * 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;
-}