@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/adapter/index.ts

@@ -0,0 +1,139 @@
+/**
+ * Engine adapter layer — all external dependency interfaces unified here.
+ *
+ * This directory is the **single source of truth** for every interface
+ * the engine uses to talk to the outside world.
+ *
+ * ## Two-layer DI architecture
+ *
+ * ### Layer 1: EngineAdapters (构造参数注入 — preferred)
+ *
+ * Used for capabilities consumed within the pipeline call stack.
+ * Injected once via {@link CoreGatewayContext.adapters}, threaded
+ * through {@link InboundPipelineDeps.adapters}, consumed by stages.
+ *
+ * - {@link HistoryPort} — group history record/build/clear
+ * - {@link MentionGatePort} — mention + command gate evaluation
+ * - {@link AudioConvertPort} — inbound SILK→WAV conversion
+ * - {@link OutboundAudioPort} — outbound WAV→SILK conversion
+ * - {@link CommandsPort} — slash-command version/approve dependencies
+ *
+ * ### Layer 2: PlatformAdapter (global singleton — leaf utilities)
+ *
+ * Used by leaf utility functions (`file-utils`, `image-size`,
+ * `platform`, `config/resolve`) that sit outside the pipeline and
+ * cannot receive a `deps` parameter. Registered once at startup.
+ *
+ * - {@link PlatformAdapter} — SSRF, secrets, media fetch, temp dir
+ */
+
+import type { FetchMediaOptions, FetchMediaResult, SecretInputRef } from "./types.js";
+
+// ============ EngineAdapters (aggregated port injection) ============
+
+/**
+ * Aggregated adapter ports injected via `CoreGatewayContext.adapters`.
+ *
+ * All fields are required — the bridge layer must provide every adapter.
+ * The engine no longer falls back to built-in implementations.
+ */
+export interface EngineAdapters {
+  /** Group history record/build/clear — backed by SDK `reply-history`. */
+  history: import("./history.port.js").HistoryPort;
+  /** Mention + command gate evaluation — backed by SDK `channel-mention-gating`. */
+  mentionGate: import("./mention-gate.port.js").MentionGatePort;
+  /** Inbound audio conversion (SILK→WAV, voice detection). */
+  audioConvert: import("./audio.port.js").AudioConvertPort;
+  /** Outbound audio conversion (WAV→SILK, audio detection). */
+  outboundAudio: import("./audio.port.js").OutboundAudioPort;
+  /** Slash-command dependencies (version, approve runtime). */
+  commands: import("./commands.port.js").CommandsPort;
+}
+
+// ============ PlatformAdapter (global singleton — leaf utilities) ============
+
+/** Platform adapter that leaf utilities use for framework-specific operations. */
+export interface PlatformAdapter {
+  /** Validate that a remote URL is safe to fetch (SSRF protection). */
+  validateRemoteUrl(url: string, options?: { allowPrivate?: boolean }): Promise<void>;
+
+  /** Resolve a secret value (SecretInput or plain string) to a plain string. */
+  resolveSecret(value: string | SecretInputRef | undefined): Promise<string | undefined>;
+
+  /** Download a remote file to a local directory. Returns the local file path. */
+  downloadFile(url: string, destDir: string, filename?: string): Promise<string>;
+
+  /**
+   * Fetch remote media with SSRF protection.
+   * Replaces direct usage of `fetchRemoteMedia` from `plugin-sdk/media-runtime`.
+   */
+  fetchMedia(options: FetchMediaOptions): Promise<FetchMediaResult>;
+
+  /** Return the preferred temporary directory for the platform. */
+  getTempDir(): string;
+
+  /** Check whether a secret input value has been configured (non-empty). */
+  hasConfiguredSecret(value: unknown): boolean;
+
+  /**
+   * Normalize a raw SecretInput value into a plain string.
+   * For unresolved references (e.g. `$secret:xxx`), returns the raw reference string.
+   */
+  normalizeSecretInputString(value: unknown): string | undefined;
+
+  /**
+   * Resolve a SecretInput value into the final plain-text secret.
+   * For secret references, resolves them to actual values via the platform's secret store.
+   */
+  resolveSecretInputString(params: { value: unknown; path: string }): string | undefined;
+
+  /**
+   * Submit an approval decision to the framework's approval gateway.
+   * Optional — only available when the framework supports approvals.
+   * Returns true if the decision was submitted successfully.
+   */
+  resolveApproval?(approvalId: string, decision: string): Promise<boolean>;
+}
+
+let _adapter: PlatformAdapter | null = null;
+let _adapterFactory: (() => PlatformAdapter) | null = null;
+
+/** Register the platform adapter. Called once during startup. */
+export function registerPlatformAdapter(adapter: PlatformAdapter): void {
+  _adapter = adapter;
+}
+
+/**
+ * Register a factory that creates the PlatformAdapter on first access.
+ *
+ * This decouples adapter availability from side-effect import ordering.
+ * The factory is invoked at most once — on the first `getPlatformAdapter()`
+ * call when no adapter has been explicitly registered yet.
+ */
+export function registerPlatformAdapterFactory(factory: () => PlatformAdapter): void {
+  _adapterFactory = factory;
+}
+
+/**
+ * Get the registered platform adapter.
+ *
+ * If no adapter has been explicitly registered yet but a factory was provided
+ * via `registerPlatformAdapterFactory()`, the factory is invoked to create
+ * and register the adapter automatically.
+ */
+export function getPlatformAdapter(): PlatformAdapter {
+  if (!_adapter && _adapterFactory) {
+    _adapter = _adapterFactory();
+  }
+  if (!_adapter) {
+    throw new Error(
+      "PlatformAdapter not registered. Call registerPlatformAdapter() during bootstrap.",
+    );
+  }
+  return _adapter;
+}
+
+/** Check whether a platform adapter has been registered (or can be created from a factory). */
+export function hasPlatformAdapter(): boolean {
+  return _adapter !== null || _adapterFactory !== null;
+}

package/src/engine/adapter/mention-gate.port.ts

@@ -0,0 +1,50 @@
+/**
+ * Mention gate port — abstracts the SDK's `resolveInboundMentionDecision`
+ * + `resolveControlCommandGate` into a single interface.
+ *
+ * The engine's `resolveGroupMessageGate` (Layer 1: ignoreOtherMentions)
+ * is QQ-specific and stays in `group/message-gating.ts`. Layer 2+3
+ * (command gating + mention gating + command bypass) delegate to this port.
+ */
+
+/** Implicit mention kind aligned with SDK's `InboundImplicitMentionKind`. */
+type ImplicitMentionKind = "reply_to_bot" | "quoted_bot" | "bot_thread_participant" | "native";
+
+/** Facts about the current message's mention state. */
+export interface MentionFacts {
+  canDetectMention: boolean;
+  wasMentioned: boolean;
+  hasAnyMention?: boolean;
+  implicitMentionKinds?: readonly ImplicitMentionKind[];
+}
+
+/** Policy configuration for the mention gate. */
+export interface MentionPolicy {
+  isGroup: boolean;
+  requireMention: boolean;
+  allowTextCommands: boolean;
+  hasControlCommand: boolean;
+  commandAuthorized: boolean;
+}
+
+/** Result of the mention gate evaluation. */
+export interface MentionGateDecision {
+  effectiveWasMentioned: boolean;
+  shouldSkip: boolean;
+  shouldBypassMention: boolean;
+  implicitMention: boolean;
+}
+
+export interface MentionGatePort {
+  /**
+   * Evaluate whether the message should be skipped based on mention
+   * policy, command bypass, and implicit mention rules.
+   *
+   * Equivalent to SDK's `resolveInboundMentionDecision` with the
+   * command-bypass logic folded in.
+   */
+  resolveInboundMentionDecision(params: {
+    facts: MentionFacts;
+    policy: MentionPolicy;
+  }): MentionGateDecision;
+}

package/src/engine/adapter/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared types used by the PlatformAdapter interface.
+ */
+
+/** Reference to a secret stored in the platform's secret management system. */
+export interface SecretInputRef {
+  source: "env" | "file" | "config";
+  id: string;
+}
+
+/** Options for fetching remote media through the platform adapter. */
+export interface FetchMediaOptions {
+  url: string;
+  /** Hint for the local filename when saving. */
+  filePathHint?: string;
+  /** Maximum bytes to download. */
+  maxBytes?: number;
+  /** Maximum redirects to follow. */
+  maxRedirects?: number;
+  /** SSRF policy configuration. */
+  ssrfPolicy?: SsrfPolicyConfig;
+  /** Extra fetch() RequestInit options. */
+  requestInit?: RequestInit;
+}
+
+/** Result of a remote media fetch operation. */
+export interface FetchMediaResult {
+  buffer: Buffer;
+  fileName?: string;
+}
+
+/** SSRF policy configuration — platform-agnostic subset. */
+export interface SsrfPolicyConfig {
+  /** Hostnames that are always allowed (supports `*.example.com` wildcards). */
+  hostnameAllowlist?: string[];
+  /** Whether to allow RFC 2544 benchmark ranges (198.18.0.0/15). */
+  allowRfc2544BenchmarkRange?: boolean;
+}

package/src/engine/api/api-client.ts

@@ -0,0 +1,212 @@
+/**
+ * Core HTTP client for the QQ Open Platform REST API.
+ *
+ * Key improvements over the old `src/api.ts#apiRequest`:
+ * - `ApiClient` is an **instance** — config (baseUrl, timeout, logger, UA)
+ *   is injected via the constructor, eliminating module-level globals.
+ * - Throws structured `ApiError` with httpStatus, bizCode, and path fields.
+ * - Detects HTML error pages from CDN/gateway and returns user-friendly messages.
+ * - `redactBodyKeys` replaces the hardcoded `file_data` redaction.
+ */
+
+import { ApiError, type ApiClientConfig, type EngineLogger } from "../types.js";
+import { formatErrorMessage } from "../utils/format.js";
+
+const DEFAULT_BASE_URL = "https://api.sgroup.qq.com";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const FILE_UPLOAD_TIMEOUT_MS = 120_000;
+
+interface RequestOptions {
+  /** Request timeout override in milliseconds. */
+  timeoutMs?: number;
+  /** Body keys to redact in debug logs (e.g. `['file_data']`). */
+  redactBodyKeys?: string[];
+  /**
+   * Mark the request as a file-upload call.
+   *
+   * Triggers the longer `fileUploadTimeoutMs` (default 120s) instead of the
+   * standard `defaultTimeoutMs` (default 30s). Prefer this flag over
+   * inspecting the request path; it keeps the timeout policy independent of
+   * route naming conventions.
+   */
+  uploadRequest?: boolean;
+}
+
+/**
+ * Stateful HTTP client for the QQ Open Platform.
+ *
+ * Usage:
+ * ```ts
+ * const client = new ApiClient({ logger, userAgent: 'QQBotPlugin/1.0' });
+ * const data = await client.request<{ url: string }>(token, 'GET', '/gateway');
+ * ```
+ */
+export class ApiClient {
+  private readonly baseUrl: string;
+  private readonly defaultTimeoutMs: number;
+  private readonly fileUploadTimeoutMs: number;
+  private readonly logger?: EngineLogger;
+  private readonly resolveUserAgent: () => string;
+
+  constructor(config: ApiClientConfig = {}) {
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.defaultTimeoutMs = config.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fileUploadTimeoutMs = config.fileUploadTimeoutMs ?? FILE_UPLOAD_TIMEOUT_MS;
+    this.logger = config.logger;
+    const ua = config.userAgent ?? "QQBotPlugin/unknown";
+    this.resolveUserAgent = typeof ua === "function" ? ua : () => ua;
+  }
+
+  /**
+   * Send an authenticated JSON request to the QQ Open Platform.
+   *
+   * @param accessToken - Bearer token (`QQBot {token}`).
+   * @param method - HTTP method.
+   * @param path - API path (appended to baseUrl).
+   * @param body - Optional JSON body.
+   * @param options - Optional request overrides.
+   * @returns Parsed JSON response.
+   * @throws {ApiError} On HTTP or parse errors.
+   */
+  async request<T = unknown>(
+    accessToken: string,
+    method: string,
+    path: string,
+    body?: unknown,
+    options?: RequestOptions,
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      Authorization: `QQBot ${accessToken}`,
+      "Content-Type": "application/json",
+      "User-Agent": this.resolveUserAgent(),
+    };
+
+    const isFileUpload =
+      options?.uploadRequest === true ||
+      // Back-compat: legacy callers that predate the explicit `uploadRequest`
+      // flag still get the long timeout when hitting file endpoints. New
+      // code should always pass `uploadRequest: true` explicitly.
+      path.includes("/files") ||
+      path.includes("/upload_prepare") ||
+      path.includes("/upload_part_finish");
+    const timeout =
+      options?.timeoutMs ?? (isFileUpload ? this.fileUploadTimeoutMs : this.defaultTimeoutMs);
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const fetchInit: RequestInit = {
+      method,
+      headers,
+      signal: controller.signal,
+    };
+
+    if (body) {
+      fetchInit.body = JSON.stringify(body);
+    }
+
+    // Debug logging with optional body redaction.
+    this.logger?.debug?.(`[qqbot:api] >>> ${method} ${url} (timeout: ${timeout}ms)`);
+    if (body && this.logger?.debug) {
+      const logBody = { ...(body as Record<string, unknown>) };
+      for (const key of options?.redactBodyKeys ?? ["file_data"]) {
+        if (typeof logBody[key] === "string") {
+          logBody[key] = `<redacted ${logBody[key].length} chars>`;
+        }
+      }
+      this.logger.debug(`[qqbot:api] >>> Body: ${JSON.stringify(logBody)}`);
+    }
+
+    let res: Response;
+    try {
+      res = await fetch(url, fetchInit);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError") {
+        this.logger?.error?.(`[qqbot:api] <<< Timeout after ${timeout}ms`);
+        throw new ApiError(`Request timeout [${path}]: exceeded ${timeout}ms`, 0, path);
+      }
+      this.logger?.error?.(`[qqbot:api] <<< Network error: ${formatErrorMessage(err)}`);
+      throw new ApiError(`Network error [${path}]: ${formatErrorMessage(err)}`, 0, path);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    // Log response status and trace ID.
+    const traceId = res.headers.get("x-tps-trace-id") ?? "";
+    this.logger?.info?.(
+      `[qqbot:api] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`,
+    );
+
+    let rawBody: string;
+    try {
+      rawBody = await res.text();
+    } catch (err) {
+      throw new ApiError(
+        `Failed to read response [${path}]: ${formatErrorMessage(err)}`,
+        res.status,
+        path,
+      );
+    }
+    this.logger?.debug?.(`[qqbot:api] <<< Body: ${rawBody}`);
+
+    // Detect non-JSON responses (HTML gateway errors, CDN rate-limit pages).
+    const contentType = res.headers.get("content-type") ?? "";
+    const isHtmlResponse = contentType.includes("text/html") || rawBody.trimStart().startsWith("<");
+
+    if (!res.ok) {
+      if (isHtmlResponse) {
+        const statusHint =
+          res.status === 502 || res.status === 503 || res.status === 504
+            ? "调用发生异常，请稍候重试"
+            : res.status === 429
+              ? "请求过于频繁，已被限流"
+              : `开放平台返回 HTTP ${res.status}`;
+        throw new ApiError(`${statusHint}（${path}），请稍后重试`, res.status, path);
+      }
+
+      // JSON error response.
+      try {
+        const error = JSON.parse(rawBody) as {
+          message?: string;
+          code?: number;
+          err_code?: number;
+        };
+        const bizCode = error.code ?? error.err_code;
+        throw new ApiError(
+          `API Error [${path}]: ${error.message ?? rawBody}`,
+          res.status,
+          path,
+          bizCode,
+          error.message,
+        );
+      } catch (parseErr) {
+        if (parseErr instanceof ApiError) {
+          throw parseErr;
+        }
+        throw new ApiError(
+          `API Error [${path}] HTTP ${res.status}: ${rawBody.slice(0, 200)}`,
+          res.status,
+          path,
+        );
+      }
+    }
+
+    // Successful response but not JSON (extreme edge case).
+    if (isHtmlResponse) {
+      throw new ApiError(
+        `QQ 服务端返回了非 JSON 响应（${path}），可能是临时故障，请稍后重试`,
+        res.status,
+        path,
+      );
+    }
+
+    try {
+      return JSON.parse(rawBody) as T;
+    } catch {
+      throw new ApiError(`开放平台响应格式异常（${path}），请稍后重试`, res.status, path);
+    }
+  }
+}