@gakr-gakr/qqbot 0.1.0

package/src/engine/adapter/audio.port.ts

@@ -0,0 +1,27 @@
+/**
+ * Audio port — abstracts inbound + outbound audio conversion operations.
+ *
+ * The engine defines this interface; the bridge layer provides an
+ * implementation backed by `engine/utils/audio.js` functions.
+ */
+
+/** Inbound audio conversion (SILK→WAV, voice detection, duration formatting). */
+export interface AudioConvertPort {
+  convertSilkToWav(
+    silkPath: string,
+    outputDir: string,
+  ): Promise<{ wavPath: string; duration: number } | null>;
+  isVoiceAttachment(att: { content_type: string; filename?: string }): boolean;
+  formatDuration(seconds: number): string;
+}
+
+/** Outbound audio conversion (WAV→SILK, audio detection, transcoding). */
+export interface OutboundAudioPort {
+  audioFileToSilkBase64(
+    audioPath: string,
+    directUploadFormats?: string[],
+  ): Promise<string | undefined>;
+  isAudioFile(pathOrUrl: string, mimeType?: string): boolean;
+  shouldTranscodeVoice(filePath: string): boolean;
+  waitForFile(filePath: string, maxWaitMs?: number): Promise<number>;
+}

package/src/engine/adapter/commands.port.ts

@@ -0,0 +1,22 @@
+/**
+ * Commands port — abstracts slash-command dependencies injected by the
+ * bridge layer (version resolvers, approve runtime getter).
+ *
+ * Eliminates global `register*` singletons in `slash-commands-impl.ts`.
+ */
+
+import type { PluginRuntime } from "autobot/plugin-sdk/core";
+
+/** Runtime getter shape for the `/bot-approve` command. */
+export type ApproveRuntimeGetter = () => {
+  config: Pick<PluginRuntime["config"], "current" | "replaceConfigFile">;
+};
+
+export interface CommandsPort {
+  /** Resolve the framework runtime version string. */
+  resolveVersion: () => string;
+  /** Plugin version string (e.g. "1.2.3"). */
+  pluginVersion: string;
+  /** Runtime getter for `/bot-approve` config management. */
+  approveRuntimeGetter?: ApproveRuntimeGetter;
+}

package/src/engine/adapter/history.port.ts

@@ -0,0 +1,52 @@
+/**
+ * History port — abstracts the group history cache operations.
+ *
+ * The engine defines this interface; the bridge layer provides an
+ * implementation backed by SDK `reply-history` functions. The engine's
+ * built-in implementation in `group/history.ts` is used as the default
+ * when no adapter is injected (standalone build).
+ */
+
+/** Minimal history entry shape expected by the port. */
+export interface HistoryEntryLike {
+  sender: string;
+  body: string;
+  timestamp?: number;
+  messageId?: string;
+}
+
+export interface HistoryPort {
+  /**
+   * Record a non-@ message into the pending history buffer.
+   * No-op when `limit <= 0` or `entry` is missing.
+   */
+  recordPendingHistoryEntry<T extends HistoryEntryLike>(params: {
+    historyMap: Map<string, T[]>;
+    historyKey: string;
+    entry?: T | null;
+    limit: number;
+  }): T[];
+
+  /**
+   * Build the full user-message string prefixed with buffered history.
+   * Returns `currentMessage` unchanged when no history exists.
+   */
+  buildPendingHistoryContext(params: {
+    historyMap: Map<string, HistoryEntryLike[]>;
+    historyKey: string;
+    limit: number;
+    currentMessage: string;
+    formatEntry: (entry: HistoryEntryLike) => string;
+    lineBreak?: string;
+  }): string;
+
+  /**
+   * Clear a group's pending history buffer.
+   * No-op when `limit <= 0`.
+   */
+  clearPendingHistory(params: {
+    historyMap: Map<string, HistoryEntryLike[]>;
+    historyKey: string;
+    limit: number;
+  }): void;
+}

package/src/engine/adapter/index.ts

@@ -0,0 +1,76 @@
+import type { ResolvedChannelMessageIngress } from "autobot/plugin-sdk/channel-ingress-runtime";
+import type { EffectivePolicyInput } from "../access/resolve-policy.js";
+import type { FetchMediaOptions, FetchMediaResult, SecretInputRef } from "./types.js";
+
+export type QQBotInboundAccess = ResolvedChannelMessageIngress;
+
+export interface AccessPort {
+  resolveInboundAccess(
+    input: EffectivePolicyInput & {
+      cfg: unknown;
+      accountId: string;
+      isGroup: boolean;
+      senderId: string;
+      conversationId: string;
+    },
+  ): QQBotInboundAccess | Promise<QQBotInboundAccess>;
+
+  resolveSlashCommandAuthorization(input: {
+    cfg: unknown;
+    accountId: string;
+    isGroup: boolean;
+    senderId: string;
+    conversationId: string;
+    allowFrom?: Array<string | number>;
+    groupAllowFrom?: Array<string | number>;
+    commandsAllowFrom?: Array<string | number>;
+  }): boolean | Promise<boolean>;
+}
+
+export interface EngineAdapters {
+  history: import("./history.port.js").HistoryPort;
+  mentionGate: import("./mention-gate.port.js").MentionGatePort;
+  access: AccessPort;
+  audioConvert: import("./audio.port.js").AudioConvertPort;
+  outboundAudio: import("./audio.port.js").OutboundAudioPort;
+  commands: import("./commands.port.js").CommandsPort;
+}
+
+export interface PlatformAdapter {
+  validateRemoteUrl(url: string, options?: { allowPrivate?: boolean }): Promise<void>;
+  resolveSecret(value: string | SecretInputRef | undefined): Promise<string | undefined>;
+  downloadFile(url: string, destDir: string, filename?: string): Promise<string>;
+  fetchMedia(options: FetchMediaOptions): Promise<FetchMediaResult>;
+  getTempDir(): string;
+  hasConfiguredSecret(value: unknown): boolean;
+  normalizeSecretInputString(value: unknown): string | undefined;
+  resolveSecretInputString(params: { value: unknown; path: string }): string | undefined;
+  resolveApproval?(approvalId: string, decision: string): Promise<boolean>;
+}
+
+let platformAdapter: PlatformAdapter | null = null;
+let platformAdapterFactory: (() => PlatformAdapter) | null = null;
+
+export function registerPlatformAdapter(adapter: PlatformAdapter): void {
+  platformAdapter = adapter;
+}
+
+export function registerPlatformAdapterFactory(factory: () => PlatformAdapter): void {
+  platformAdapterFactory = factory;
+}
+
+export function getPlatformAdapter(): PlatformAdapter {
+  if (!platformAdapter && platformAdapterFactory) {
+    platformAdapter = platformAdapterFactory();
+  }
+  if (!platformAdapter) {
+    throw new Error(
+      "PlatformAdapter not registered. Call registerPlatformAdapter() during bootstrap.",
+    );
+  }
+  return platformAdapter;
+}
+
+export function hasPlatformAdapter(): boolean {
+  return platformAdapter !== null || platformAdapterFactory !== 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);
+    }
+  }
+}