@gakr-gakr/qqbot 0.1.0

package/src/engine/gateway/types.ts

@@ -0,0 +1,230 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/core";
+import type { EngineLogger } from "../types.js";
+export type { EngineLogger };
+
+import type { GatewayAccount as _GatewayAccount } from "../types.js";
+export type GatewayAccount = _GatewayAccount;
+
+export interface GatewayPluginRuntime {
+  channel: {
+    activity: {
+      record: (params: {
+        channel: string;
+        accountId: string;
+        direction: "inbound" | "outbound";
+      }) => void;
+    };
+    routing: {
+      resolveAgentRoute: (params: {
+        cfg: unknown;
+        channel: string;
+        accountId: string;
+        peer: { kind: "group" | "direct"; id: string };
+      }) => { sessionKey: string; accountId: string; agentId?: string };
+    };
+    commands?: {
+      isControlCommandMessage?: (text?: string, cfg?: unknown) => boolean;
+    };
+    reply: {
+      dispatchReplyWithBufferedBlockDispatcher: (params: unknown) => Promise<unknown>;
+      resolveEffectiveMessagesConfig: (
+        cfg: unknown,
+        agentId?: string,
+      ) => { responsePrefix?: string };
+      finalizeInboundContext: (fields: Record<string, unknown>) => unknown;
+      formatInboundEnvelope: (params: unknown) => string;
+      resolveEnvelopeFormatOptions: (cfg: unknown) => unknown;
+    };
+    session: {
+      resolveStorePath: (store: unknown, params: { agentId: string }) => string;
+      recordInboundSession: (params: unknown) => Promise<unknown>;
+    };
+    turn: {
+      run: (params: unknown) => Promise<unknown>;
+    };
+    text: {
+      chunkMarkdownText: (text: string, limit: number) => string[];
+    };
+  };
+  tts: {
+    textToSpeech: (params: {
+      text: string;
+      cfg: unknown;
+      channel: string;
+      accountId?: string;
+    }) => Promise<{
+      success: boolean;
+      audioPath?: string;
+      provider?: string;
+      outputFormat?: string;
+      error?: string;
+    }>;
+  };
+  config?: {
+    current: () => Record<string, unknown>;
+    replaceConfigFile: (params: {
+      nextConfig: unknown;
+      afterWrite: { mode: "auto" };
+    }) => Promise<unknown>;
+  };
+}
+
+export type { ProcessedAttachments } from "./inbound-attachments.js";
+
+export interface OutboundResult {
+  channel: string;
+  messageId?: string;
+  timestamp?: string | number;
+  error?: string;
+}
+
+export type { RefAttachmentSummary } from "../ref/types.js";
+
+export interface WSPayload {
+  op: number;
+  d: unknown;
+  s?: number;
+  t?: string;
+}
+
+interface RawMessageAttachment {
+  content_type: string;
+  url: string;
+  filename?: string;
+  voice_wav_url?: string;
+  asr_refer_text?: string;
+}
+
+interface RawMsgElement {
+  msg_idx?: string;
+  content?: string;
+  attachments?: Array<
+    RawMessageAttachment & {
+      height?: number;
+      width?: number;
+      size?: number;
+    }
+  >;
+}
+
+export interface C2CMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: { user_openid: string };
+  attachments?: RawMessageAttachment[];
+  message_scene?: { ext?: string[] };
+  message_type?: number;
+  msg_elements?: RawMsgElement[];
+}
+
+export interface GuildMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: { id: string; username?: string };
+  channel_id: string;
+  guild_id: string;
+  attachments?: RawMessageAttachment[];
+  message_scene?: { ext?: string[] };
+}
+
+export interface GroupMessageEvent {
+  id: string;
+  content: string;
+  timestamp: string;
+  author: {
+    member_openid: string;
+    username?: string;
+    /** True when the sender is itself a bot. */
+    bot?: boolean;
+  };
+  group_openid: string;
+  attachments?: RawMessageAttachment[];
+  /** Optional @mentions list with per-entry is_you / member_openid / nickname. */
+  mentions?: Array<{
+    scope?: "all" | "single";
+    id?: string;
+    user_openid?: string;
+    member_openid?: string;
+    nickname?: string;
+    username?: string;
+    bot?: boolean;
+    /** `true` when this mention targets the bot itself. */
+    is_you?: boolean;
+  }>;
+  message_scene?: { source?: string; ext?: string[] };
+  message_type?: number;
+  msg_elements?: RawMsgElement[];
+}
+
+// ============ Gateway Context ============
+
+import type { EngineAdapters } from "../adapter/index.js";
+
+/**
+ * Group-chat behaviour options.
+ *
+ * Grouped under a dedicated sub-object on {@link CoreGatewayContext} so
+ * future additions (admin lookup, proactive push, per-group toggles)
+ * don't keep polluting the top-level context type.
+ */
+interface GatewayGroupOptions {
+  /**
+   * Whether group-chat gating is enabled. Defaults to `true`; set to
+   * `false` to disable all group processing (e.g. for a DM-only smoke
+   * test). When disabled, the engine does not allocate a history
+   * buffer and does not instantiate the session-store reader.
+   */
+  enabled?: boolean;
+  /**
+   * Whether the framework has text-based control commands enabled. When
+   * `false`, the group gate skips the "unauthorized command" check and
+   * the command-bypass path.
+   */
+  allowTextCommands?: boolean;
+  /**
+   * Optional probe that returns true when `content` is a recognised
+   * control command. Injected to avoid hard-coding a command list in
+   * the engine. When omitted, no message is treated as a control
+   * command and the bypass path never activates.
+   */
+  isControlCommand?: (content: string) => boolean;
+  /**
+   * Platform hook that contributes a channel-level group intro hint
+   * (e.g. "当前群: 开发讨论组"). Invoked per-group when building the
+   * system prompt.
+   */
+  resolveIntroHint?: (params: {
+    cfg: unknown;
+    accountId: string;
+    groupId: string;
+  }) => string | undefined;
+  /**
+   * Session-store reader for the `/activation` command override. When
+   * omitted, the engine loads a default node-based reader lazily.
+   */
+  sessionStoreReader?: import("../group/activation.js").SessionStoreReader;
+}
+
+/** Full gateway startup context. */
+export interface CoreGatewayContext {
+  account: GatewayAccount;
+  abortSignal: AbortSignal;
+  cfg: AutoBotConfig;
+  onReady?: (data: unknown) => void;
+  /**
+   * Invoked when a RESUMED event is received after reconnect.
+   * Falls back to `onReady` when not provided so existing callers
+   * keep their current behaviour.
+   */
+  onResumed?: (data: unknown) => void;
+  onError?: (error: Error) => void;
+  log?: EngineLogger;
+  /** PluginRuntime injected by the framework — same object in both versions. */
+  runtime: GatewayPluginRuntime;
+  /** Group-chat tuning options. */
+  group?: GatewayGroupOptions;
+  /** Adapter ports — delegates audio, history, mention gating, commands to bridge implementations. */
+  adapters: EngineAdapters;
+}

package/src/engine/gateway/typing-keepalive.ts

@@ -0,0 +1,102 @@
+/**
+ * Periodically refresh C2C typing state while a response is in progress.
+ *
+ * All I/O operations are injected via constructor parameters so this
+ * module has zero external dependencies and can run in both plugin versions.
+ */
+
+import { formatErrorMessage } from "../utils/format.js";
+
+/** Function that sends a typing indicator to one user. */
+type SendInputNotifyFn = (
+  token: string,
+  openid: string,
+  msgId: string | undefined,
+  inputSecond: number,
+) => Promise<unknown>;
+
+/** Refresh every 5s for the QQ API's 10s input-notify window. */
+const TYPING_INTERVAL_MS = 5_000;
+export const TYPING_INPUT_SECOND = 10;
+const QQ_C2C_PASSIVE_REPLY_LIMIT = 5;
+const INITIAL_TYPING_NOTIFY_COUNT = 1;
+const FINAL_REPLY_RESERVE_COUNT = 1;
+export const TYPING_RENEWAL_LIMIT =
+  QQ_C2C_PASSIVE_REPLY_LIMIT - INITIAL_TYPING_NOTIFY_COUNT - FINAL_REPLY_RESERVE_COUNT;
+
+export class TypingKeepAlive {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+  private renewalsRemaining = TYPING_RENEWAL_LIMIT;
+
+  constructor(
+    private readonly getToken: () => Promise<string>,
+    private readonly clearCache: () => void,
+    private readonly sendInputNotify: SendInputNotifyFn,
+    private readonly openid: string,
+    private readonly msgId: string | undefined,
+    private readonly log?: {
+      info: (msg: string) => void;
+      error: (msg: string) => void;
+      debug?: (msg: string) => void;
+    },
+  ) {}
+
+  /** Start periodic keep-alive sends. */
+  start(): void {
+    if (this.stopped) {
+      return;
+    }
+    this.timer = setInterval(() => {
+      if (this.stopped) {
+        this.stop();
+        return;
+      }
+      this.send().catch(() => {});
+    }, TYPING_INTERVAL_MS);
+  }
+
+  /** Stop periodic keep-alive sends. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  private async send(): Promise<void> {
+    try {
+      const token = await this.getToken();
+      await this.sendAttempt(token);
+    } catch (err) {
+      try {
+        this.clearCache();
+        const token = await this.getToken();
+        await this.sendAttempt(token);
+      } catch {
+        this.log?.debug?.(
+          `Typing keep-alive failed for ${this.openid}: ${formatErrorMessage(err)}`,
+        );
+      }
+    }
+  }
+
+  private async sendAttempt(token: string): Promise<void> {
+    if (this.stopped || this.renewalsRemaining <= 0) {
+      this.stop();
+      return;
+    }
+
+    this.renewalsRemaining--;
+    try {
+      await this.sendInputNotify(token, this.openid, this.msgId, TYPING_INPUT_SECOND);
+      this.log?.debug?.(`Typing keep-alive sent to ${this.openid}`);
+    } finally {
+      if (this.renewalsRemaining <= 0) {
+        this.log?.debug?.(`Typing keep-alive budget exhausted for ${this.openid}`);
+        this.stop();
+      }
+    }
+  }
+}

package/src/engine/gateway/ws-client.ts

@@ -0,0 +1,16 @@
+import type { Agent } from "node:http";
+import { resolveAmbientNodeProxyAgent } from "autobot/plugin-sdk/extension-shared";
+import WebSocket from "ws";
+
+export interface QQWSClientOptions {
+  gatewayUrl: string;
+  userAgent: string;
+}
+
+export async function createQQWSClient(options: QQWSClientOptions): Promise<WebSocket> {
+  const wsAgent = await resolveAmbientNodeProxyAgent<Agent>();
+  return new WebSocket(options.gatewayUrl, {
+    headers: { "User-Agent": options.userAgent },
+    ...(wsAgent ? { agent: wsAgent } : {}),
+  });
+}

package/src/engine/group/activation.ts

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+
+export type GroupActivationMode = "mention" | "always";
+
+export interface SessionStoreReader {
+  read(params: {
+    cfg: Record<string, unknown>;
+    agentId: string;
+  }): Record<string, { groupActivation?: string }> | null;
+}
+
+export function resolveGroupActivation(params: {
+  cfg: Record<string, unknown>;
+  agentId: string;
+  sessionKey: string;
+  configRequireMention: boolean;
+  sessionStoreReader?: SessionStoreReader;
+}): GroupActivationMode {
+  const fallback: GroupActivationMode = params.configRequireMention ? "mention" : "always";
+
+  const store = params.sessionStoreReader?.read({
+    cfg: params.cfg,
+    agentId: params.agentId,
+  });
+  if (!store) {
+    return fallback;
+  }
+
+  const entry = store[params.sessionKey];
+  if (!entry?.groupActivation) {
+    return fallback;
+  }
+
+  const normalized = entry.groupActivation.trim().toLowerCase();
+  if (normalized === "mention" || normalized === "always") {
+    return normalized;
+  }
+  return fallback;
+}
+
+function resolveSessionStorePath(
+  cfg: Record<string, unknown>,
+  agentId: string | undefined,
+): string {
+  const resolvedAgentId = agentId || "default";
+
+  const session =
+    typeof cfg.session === "object" && cfg.session !== null
+      ? (cfg.session as { store?: unknown })
+      : undefined;
+  const rawStore = typeof session?.store === "string" ? session.store : undefined;
+
+  if (rawStore) {
+    let expanded = rawStore;
+    if (expanded.includes("{agentId}")) {
+      expanded = expanded.replaceAll("{agentId}", resolvedAgentId);
+    }
+    if (expanded.startsWith("~")) {
+      const home = process.env.HOME || process.env.USERPROFILE || "";
+      expanded = expanded.replace(/^~/, home);
+    }
+    return path.resolve(expanded);
+  }
+
+  const stateDir =
+    process.env.AUTOBOT_STATE_DIR?.trim() ||
+    process.env.CLAWDBOT_STATE_DIR?.trim() ||
+    path.join(process.env.HOME || process.env.USERPROFILE || "", ".autobot");
+  return path.join(stateDir, "agents", resolvedAgentId, "sessions", "sessions.json");
+}
+
+export function createNodeSessionStoreReader(): SessionStoreReader {
+  return {
+    read: ({ cfg, agentId }) => {
+      try {
+        const storePath = resolveSessionStorePath(cfg, agentId);
+        if (!fs.existsSync(storePath)) {
+          return null;
+        }
+        const raw = fs.readFileSync(storePath, "utf-8");
+        return JSON.parse(raw) as Record<string, { groupActivation?: string }>;
+      } catch {
+        return null;
+      }
+    },
+  };
+}