@openclaw/qqbot 2026.5.2 → 2026.5.3-beta.1

package/src/engine/adapter/index.ts

@@ -1,139 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,38 +0,0 @@
-/**
- * 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

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