@gakr-gakr/qqbot 0.1.0

package/src/engine/gateway/active-cfg.ts

@@ -0,0 +1,52 @@
+/**
+ * Active runtime config provider for the QQBot engine.
+ *
+ * Routing must re-evaluate `bindings[]` on every inbound message so that
+ * peer/account binding edits made via the CLI take effect without
+ * restarting the gateway. The provider hides the per-event lookup
+ * behind a typed seam and falls back to the startup snapshot when the
+ * runtime registry getter throws (e.g. snapshot not yet initialised).
+ *
+ * Issue #69546.
+ */
+
+import type { AutoBotConfig } from "autobot/plugin-sdk/core";
+import { getRuntimeConfig } from "autobot/plugin-sdk/runtime-config-snapshot";
+
+export type GatewayCfg = AutoBotConfig;
+
+export type GatewayCfgLoader = () => AutoBotConfig;
+
+export interface ActiveCfgProvider {
+  getActiveCfg(): AutoBotConfig;
+}
+
+export interface ActiveCfgProviderOptions {
+  fallback: AutoBotConfig;
+  load?: GatewayCfgLoader;
+}
+
+export function createActiveCfgProvider(options: ActiveCfgProviderOptions): ActiveCfgProvider {
+  const loader = options.load ?? defaultGatewayCfgLoader;
+  const fallback = options.fallback;
+  return {
+    getActiveCfg(): AutoBotConfig {
+      return resolveActiveCfg(loader, fallback);
+    },
+  };
+}
+
+export function resolveActiveCfg(
+  loader: GatewayCfgLoader,
+  fallback: AutoBotConfig,
+): AutoBotConfig {
+  try {
+    return loader();
+  } catch {
+    return fallback;
+  }
+}
+
+function defaultGatewayCfgLoader(): AutoBotConfig {
+  return getRuntimeConfig();
+}

package/src/engine/gateway/codec.ts

@@ -0,0 +1,47 @@
+/**
+ * Gateway message decoding utilities.
+ *
+ * Extracted from `gateway.ts` — handles the various data formats that
+ * the QQ Bot WebSocket can deliver (string, Buffer, Buffer[], ArrayBuffer).
+ *
+ * Zero external dependencies beyond Node.js built-ins.
+ */
+
+/**
+ * Decode raw WebSocket `data` into a UTF-8 string.
+ *
+ * The QQ Bot gateway can send data as a plain string, a single Buffer,
+ * an array of Buffer chunks, an ArrayBuffer, or a typed array view.
+ */
+export function decodeGatewayMessageData(data: unknown): string {
+  if (typeof data === "string") {
+    return data;
+  }
+  if (Buffer.isBuffer(data)) {
+    return data.toString("utf8");
+  }
+  if (Array.isArray(data) && data.every((chunk) => Buffer.isBuffer(chunk))) {
+    return Buffer.concat(data).toString("utf8");
+  }
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data).toString("utf8");
+  }
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  }
+  return "";
+}
+
+/**
+ * Read the optional `message_scene.ext` array from an event payload.
+ *
+ * Guild, C2C, and Group events may carry a `message_scene` object
+ * with an `ext` string array used for ref-index parsing.
+ */
+export function readOptionalMessageSceneExt(event: Record<string, unknown>): string[] | undefined {
+  if (!("message_scene" in event)) {
+    return undefined;
+  }
+  const scene = event.message_scene as { ext?: string[] } | undefined;
+  return scene?.ext;
+}

package/src/engine/gateway/constants.ts

@@ -0,0 +1,117 @@
+/**
+ * QQ Bot WebSocket Gateway protocol constants.
+ *
+ * Extracted from `gateway.ts` to share between both plugin versions.
+ * Zero external dependencies.
+ */
+
+/** QQ Bot WebSocket intents grouped by permission level. */
+const INTENTS = {
+  GUILDS: 1 << 0,
+  GUILD_MEMBERS: 1 << 1,
+  PUBLIC_GUILD_MESSAGES: 1 << 30,
+  DIRECT_MESSAGE: 1 << 12,
+  GROUP_AND_C2C: 1 << 25,
+  /** Button interaction callbacks (INTERACTION_CREATE). */
+  INTERACTION: 1 << 26,
+} as const;
+
+/** Full intent mask: groups + DMs + channels + interaction. */
+export const FULL_INTENTS =
+  INTENTS.PUBLIC_GUILD_MESSAGES |
+  INTENTS.DIRECT_MESSAGE |
+  INTENTS.GROUP_AND_C2C |
+  INTENTS.INTERACTION;
+
+/** Exponential backoff delays for reconnection attempts (ms). */
+export const RECONNECT_DELAYS = [1000, 2000, 5000, 10000, 30000, 60000] as const;
+
+/** Delay after receiving a rate-limit close code (ms). */
+export const RATE_LIMIT_DELAY = 60000;
+
+/** Maximum reconnection attempts before giving up. */
+export const MAX_RECONNECT_ATTEMPTS = 100;
+
+/** How many quick disconnects before warning about permissions. */
+export const MAX_QUICK_DISCONNECT_COUNT = 3;
+
+/** A disconnect within this window (ms) counts as "quick". */
+export const QUICK_DISCONNECT_THRESHOLD = 5000;
+
+// ============ Opcode Constants ============
+
+/** Gateway opcodes used by the QQ Bot WebSocket protocol. */
+export const GatewayOp = {
+  /** Server → Client: Dispatch event (type + data). */
+  DISPATCH: 0,
+  /** Client → Server: Heartbeat. */
+  HEARTBEAT: 1,
+  /** Client → Server: Identify (initial auth). */
+  IDENTIFY: 2,
+  /** Client → Server: Resume a dropped session. */
+  RESUME: 6,
+  /** Server → Client: Request client to reconnect. */
+  RECONNECT: 7,
+  /** Server → Client: Invalid session. */
+  INVALID_SESSION: 9,
+  /** Server → Client: Hello (heartbeat interval). */
+  HELLO: 10,
+  /** Server → Client: Heartbeat ACK. */
+  HEARTBEAT_ACK: 11,
+} as const;
+
+// ============ Close Codes ============
+
+/** WebSocket close codes used by the QQ Gateway. */
+export const GatewayCloseCode = {
+  /** Normal closure — do not reconnect. */
+  NORMAL: 1000,
+  /** Authentication failed — refresh token then reconnect. */
+  AUTH_FAILED: 4004,
+  /** Session invalid — clear session, refresh token, reconnect. */
+  INVALID_SESSION: 4006,
+  /** Sequence number out of range — clear session, refresh token, reconnect. */
+  SEQ_OUT_OF_RANGE: 4007,
+  /** Rate limited — wait before reconnecting. */
+  RATE_LIMITED: 4008,
+  /** Session timed out — clear session, refresh token, reconnect. */
+  SESSION_TIMEOUT: 4009,
+  /** Server internal error (range start) — clear session, refresh token, reconnect. */
+  SERVER_ERROR_START: 4900,
+  /** Server internal error (range end). */
+  SERVER_ERROR_END: 4913,
+  /** Insufficient intents — fatal, do not reconnect. */
+  INSUFFICIENT_INTENTS: 4914,
+  /** Disallowed intents — fatal, do not reconnect. */
+  DISALLOWED_INTENTS: 4915,
+} as const;
+
+// ============ Dispatch Event Types ============
+
+/** Event type strings dispatched under opcode 0 (DISPATCH). */
+export const GatewayEvent = {
+  READY: "READY",
+  RESUMED: "RESUMED",
+  C2C_MESSAGE_CREATE: "C2C_MESSAGE_CREATE",
+  AT_MESSAGE_CREATE: "AT_MESSAGE_CREATE",
+  DIRECT_MESSAGE_CREATE: "DIRECT_MESSAGE_CREATE",
+  /** Group message that explicitly @-mentions the bot. */
+  GROUP_AT_MESSAGE_CREATE: "GROUP_AT_MESSAGE_CREATE",
+  /**
+   * Group message that does NOT mention the bot. Still dispatched to the
+   * pipeline so the group history buffer and the `requireMention=false`
+   * path can observe it.
+   */
+  GROUP_MESSAGE_CREATE: "GROUP_MESSAGE_CREATE",
+  INTERACTION_CREATE: "INTERACTION_CREATE",
+} as const;
+
+// ============ Interaction Type Constants ============
+
+/** Interaction sub-types carried in `InteractionEvent.data.type`. */
+export const InteractionType = {
+  /** Remote config query — bot reports its current claw_cfg snapshot. */
+  CONFIG_QUERY: 2001,
+  /** Remote config update — caller pushes new settings. */
+  CONFIG_UPDATE: 2002,
+} as const;

package/src/engine/gateway/event-dispatcher.ts

@@ -0,0 +1,177 @@
+/**
+ * Event dispatcher — convert raw WebSocket op=0 events into QueuedMessage objects.
+ *
+ * Pure mapping logic with zero side effects (except known-user recording).
+ * Independently testable.
+ */
+
+import { recordKnownUser } from "../session/known-users.js";
+import type { InteractionEvent } from "../types.js";
+import { parseRefIndices } from "../utils/text-parsing.js";
+import { readOptionalMessageSceneExt } from "./codec.js";
+import { GatewayEvent } from "./constants.js";
+import type { QueuedMessage } from "./message-queue.js";
+import type {
+  C2CMessageEvent,
+  GuildMessageEvent,
+  GroupMessageEvent,
+  EngineLogger,
+} from "./types.js";
+
+// ============ Dispatch result ============
+
+type DispatchResult =
+  | { action: "ready"; data: unknown; sessionId: string }
+  | { action: "resumed"; data: unknown }
+  | { action: "message"; msg: QueuedMessage }
+  | { action: "interaction"; event: InteractionEvent }
+  | { action: "ignore" };
+
+// ============ dispatchEvent ============
+
+/**
+ * Map a raw op=0 event into a structured dispatch result.
+ *
+ * Returns "message" for events that should be queued for processing,
+ * "ready"/"resumed" for session lifecycle events, and "ignore" otherwise.
+ */
+export function dispatchEvent(
+  eventType: string,
+  data: unknown,
+  accountId: string,
+  _log?: EngineLogger,
+): DispatchResult {
+  if (eventType === GatewayEvent.READY) {
+    const d = data as { session_id: string };
+    return { action: "ready", data, sessionId: d.session_id };
+  }
+
+  if (eventType === GatewayEvent.RESUMED) {
+    return { action: "resumed", data };
+  }
+
+  if (eventType === GatewayEvent.C2C_MESSAGE_CREATE) {
+    const ev = data as C2CMessageEvent;
+    recordKnownUser({
+      openid: ev.author.user_openid,
+      type: "c2c",
+      accountId,
+    });
+    const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+    return {
+      action: "message",
+      msg: {
+        type: "c2c",
+        senderId: ev.author.user_openid,
+        content: ev.content,
+        messageId: ev.id,
+        timestamp: ev.timestamp,
+        attachments: ev.attachments,
+        refMsgIdx: refs.refMsgIdx,
+        msgIdx: refs.msgIdx,
+        msgType: ev.message_type,
+        msgElements: ev.msg_elements,
+      },
+    };
+  }
+
+  if (eventType === GatewayEvent.AT_MESSAGE_CREATE) {
+    const ev = data as GuildMessageEvent;
+    const refs = parseRefIndices(
+      readOptionalMessageSceneExt(ev as unknown as Record<string, unknown>),
+    );
+    return {
+      action: "message",
+      msg: {
+        type: "guild",
+        senderId: ev.author.id,
+        senderName: ev.author.username,
+        content: ev.content,
+        messageId: ev.id,
+        timestamp: ev.timestamp,
+        channelId: ev.channel_id,
+        guildId: ev.guild_id,
+        attachments: ev.attachments,
+        refMsgIdx: refs.refMsgIdx,
+        msgIdx: refs.msgIdx,
+      },
+    };
+  }
+
+  if (eventType === GatewayEvent.DIRECT_MESSAGE_CREATE) {
+    const ev = data as GuildMessageEvent;
+    const refs = parseRefIndices(
+      readOptionalMessageSceneExt(ev as unknown as Record<string, unknown>),
+    );
+    return {
+      action: "message",
+      msg: {
+        type: "dm",
+        senderId: ev.author.id,
+        senderName: ev.author.username,
+        content: ev.content,
+        messageId: ev.id,
+        timestamp: ev.timestamp,
+        guildId: ev.guild_id,
+        attachments: ev.attachments,
+        refMsgIdx: refs.refMsgIdx,
+        msgIdx: refs.msgIdx,
+      },
+    };
+  }
+
+  if (eventType === GatewayEvent.GROUP_AT_MESSAGE_CREATE) {
+    return { action: "message", msg: buildGroupQueuedMessage(data, accountId, eventType) };
+  }
+
+  if (eventType === GatewayEvent.GROUP_MESSAGE_CREATE) {
+    return { action: "message", msg: buildGroupQueuedMessage(data, accountId, eventType) };
+  }
+
+  if (eventType === GatewayEvent.INTERACTION_CREATE) {
+    return { action: "interaction", event: data as InteractionEvent };
+  }
+
+  return { action: "ignore" };
+}
+
+/**
+ * Build a {@link QueuedMessage} from a raw QQ group event payload.
+ *
+ * Used for both `GROUP_AT_MESSAGE_CREATE` (bot was @-ed) and
+ * `GROUP_MESSAGE_CREATE` (non-@ background chatter). The only difference
+ * between the two is the carried `eventType` — downstream gating uses
+ * that to decide whether to treat the message as a bot-directed turn.
+ */
+function buildGroupQueuedMessage(
+  data: unknown,
+  accountId: string,
+  eventType: string,
+): QueuedMessage {
+  const ev = data as GroupMessageEvent;
+  recordKnownUser({
+    openid: ev.author.member_openid,
+    type: "group",
+    groupOpenid: ev.group_openid,
+    accountId,
+  });
+  const refs = parseRefIndices(ev.message_scene?.ext, ev.message_type, ev.msg_elements);
+  return {
+    type: "group",
+    senderId: ev.author.member_openid,
+    senderName: ev.author.username,
+    senderIsBot: ev.author.bot,
+    content: ev.content,
+    messageId: ev.id,
+    timestamp: ev.timestamp,
+    groupOpenid: ev.group_openid,
+    attachments: ev.attachments,
+    refMsgIdx: refs.refMsgIdx,
+    msgIdx: refs.msgIdx,
+    msgType: ev.message_type,
+    msgElements: ev.msg_elements,
+    eventType,
+    mentions: ev.mentions,
+    messageScene: ev.message_scene,
+  };
+}