@gakr-gakr/qqbot 0.1.0

package/src/bridge/tools/remind.ts

@@ -0,0 +1,91 @@
+import { callGatewayTool } from "autobot/plugin-sdk/agent-harness-runtime";
+import type {
+  AnyAgentTool,
+  AutoBotPluginApi,
+  AutoBotPluginToolContext,
+} from "autobot/plugin-sdk/core";
+import { RemindSchema, executeScheduledRemind } from "../../engine/tools/remind-logic.js";
+import type { RemindCronAction, RemindParams } from "../../engine/tools/remind-logic.js";
+import { getRequestContext } from "../../engine/utils/request-context.js";
+
+type CronGatewayCaller = (params: RemindCronAction) => Promise<unknown>;
+
+type RemindToolDeps = {
+  callCron: CronGatewayCaller;
+};
+
+const DEFAULT_GATEWAY_TIMEOUT_MS = 60_000;
+
+function unexpectedCronParams(params: never): never {
+  throw new Error(`Unsupported reminder cron action: ${JSON.stringify(params)}`);
+}
+
+const defaultDeps: RemindToolDeps = {
+  callCron: async (params) => {
+    switch (params.action) {
+      case "list":
+        return await callGatewayTool("cron.list", { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS }, {});
+      case "remove":
+        return await callGatewayTool(
+          "cron.remove",
+          { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS },
+          { jobId: params.jobId },
+        );
+      case "add":
+        return await callGatewayTool(
+          "cron.add",
+          { timeoutMs: DEFAULT_GATEWAY_TIMEOUT_MS },
+          { job: params.job },
+        );
+    }
+    return unexpectedCronParams(params);
+  },
+};
+
+export function createRemindTool(
+  toolContext: AutoBotPluginToolContext = {},
+  deps: RemindToolDeps = defaultDeps,
+): AnyAgentTool {
+  return {
+    name: "qqbot_remind",
+    label: "QQBot Reminder",
+    ownerOnly: true,
+    description:
+      "Create, list, and remove QQ reminders. " +
+      "This tool schedules Gateway cron jobs directly; do not call the cron tool after it succeeds.\n" +
+      "Create: action=add, content=message, time=schedule (to is optional, " +
+      "resolved automatically from the current conversation)\n" +
+      "List: action=list\n" +
+      "Remove: action=remove, jobId=job id from list\n" +
+      'Time examples: "5m", "1h", "0 8 * * *"',
+    parameters: RemindSchema,
+    async execute(_toolCallId, params) {
+      if (toolContext.senderIsOwner !== true) {
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                error: "QQ reminders require an owner-authorized sender.",
+              }),
+            },
+          ],
+          details: { error: "QQ reminders require an owner-authorized sender." },
+        };
+      }
+      const ctx = getRequestContext();
+      return await executeScheduledRemind(
+        params as RemindParams,
+        {
+          fallbackTo: ctx?.target ?? toolContext.deliveryContext?.to,
+          fallbackAccountId: ctx?.accountId ?? toolContext.deliveryContext?.accountId,
+        },
+        deps.callCron,
+      );
+    },
+  };
+}
+
+export function registerRemindTool(api: AutoBotPluginApi): void {
+  api.registerTool((ctx) => createRemindTool(ctx), { name: "qqbot_remind" });
+}

package/src/channel.setup.ts

@@ -0,0 +1,33 @@
+import type { ChannelPlugin } from "autobot/plugin-sdk/core";
+import "./bridge/bootstrap.js";
+import { qqbotConfigAdapter, qqbotMeta, qqbotSetupAdapterShared } from "./bridge/config-shared.js";
+import { qqbotSetupWizard } from "./bridge/setup/surface.js";
+import { qqbotChannelConfigSchema } from "./config-schema.js";
+import type { ResolvedQQBotAccount } from "./types.js";
+
+/**
+ * Setup-only QQBot plugin — lightweight subset used during `autobot onboard`
+ * and `autobot configure` without pulling the full runtime dependencies.
+ */
+export const qqbotSetupPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
+  id: "qqbot",
+  setupWizard: qqbotSetupWizard,
+  meta: {
+    ...qqbotMeta,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.qqbot"] },
+  configSchema: qqbotChannelConfigSchema,
+  config: {
+    ...qqbotConfigAdapter,
+  },
+  setup: {
+    ...qqbotSetupAdapterShared,
+  },
+};

package/src/channel.ts

@@ -0,0 +1,399 @@
+import { getExecApprovalReplyMetadata } from "autobot/plugin-sdk/approval-runtime";
+import {
+  createMessageReceiptFromOutboundResults,
+  defineChannelMessageAdapter,
+  type ChannelMessageSendResult,
+  type MessageReceiptPartKind,
+} from "autobot/plugin-sdk/channel-message";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { ChannelPlugin } from "autobot/plugin-sdk/core";
+// Register the PlatformAdapter before any core/ module is used.
+import "./bridge/bootstrap.js";
+import { getQQBotApprovalCapability } from "./bridge/approval/capability.js";
+import { qqbotConfigAdapter, qqbotMeta, qqbotSetupAdapterShared } from "./bridge/config-shared.js";
+import {
+  applyQQBotAccountConfig,
+  DEFAULT_ACCOUNT_ID,
+  resolveQQBotAccount,
+} from "./bridge/config.js";
+import type { GatewayContext } from "./bridge/gateway.js";
+import { toGatewayAccount, writeAutoBotConfigThroughRuntime } from "./bridge/narrowing.js";
+import { getQQBotRuntime } from "./bridge/runtime.js";
+import { qqbotSetupWizard } from "./bridge/setup/surface.js";
+import { qqbotChannelConfigSchema } from "./config-schema.js";
+import { loadCredentialBackup, saveCredentialBackup } from "./engine/config/credential-backup.js";
+import { clearAccountCredentials } from "./engine/config/credentials.js";
+import {
+  normalizeTarget as coreNormalizeTarget,
+  looksLikeQQBotTarget,
+} from "./engine/messaging/target-parser.js";
+import type { ResolvedQQBotAccount } from "./types.js";
+
+// Shared promise so concurrent multi-account startups serialize the dynamic
+// import of the gateway module, avoiding an ESM circular-dependency race.
+let gatewayModulePromise: Promise<typeof import("./bridge/gateway.js")> | undefined;
+function loadGatewayModule(): Promise<typeof import("./bridge/gateway.js")> {
+  gatewayModulePromise ??= import("./bridge/gateway.js");
+  return gatewayModulePromise;
+}
+
+function createQQBotSendReceipt(params: {
+  messageId?: string;
+  target: string;
+  kind: MessageReceiptPartKind;
+}) {
+  const messageId = params.messageId?.trim();
+  return createMessageReceiptFromOutboundResults({
+    results: messageId
+      ? [
+          {
+            channel: "qqbot",
+            messageId,
+            conversationId: params.target,
+          },
+        ]
+      : [],
+    threadId: params.target,
+    kind: params.kind,
+  });
+}
+
+async function sendQQBotText(params: {
+  cfg: AutoBotConfig;
+  to: string;
+  text: string;
+  accountId?: string | null;
+  replyToId?: string | null;
+}) {
+  // Ensure bridge/gateway.ts module-level registrations (audio adapter factory,
+  // platform adapter, etc.) have executed before engine code runs.
+  await loadGatewayModule();
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  const { sendText } = await import("./engine/messaging/outbound.js");
+  const result = await sendText({
+    to: params.to,
+    text: params.text,
+    accountId: params.accountId,
+    replyToId: params.replyToId,
+    account: toGatewayAccount(account),
+  });
+  return {
+    channel: "qqbot" as const,
+    messageId: result.messageId ?? "",
+    receipt: createQQBotSendReceipt({
+      messageId: result.messageId,
+      target: params.to,
+      kind: "text",
+    }),
+    meta: result.error ? { error: result.error } : undefined,
+  };
+}
+
+async function sendQQBotMedia(params: {
+  cfg: AutoBotConfig;
+  to: string;
+  text?: string | null;
+  mediaUrl?: string | null;
+  accountId?: string | null;
+  replyToId?: string | null;
+}) {
+  // Same guard as sendText — ensure adapters are registered.
+  await loadGatewayModule();
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  const { sendMedia } = await import("./engine/messaging/outbound.js");
+  const result = await sendMedia({
+    to: params.to,
+    text: params.text ?? "",
+    mediaUrl: params.mediaUrl ?? "",
+    accountId: params.accountId,
+    replyToId: params.replyToId,
+    account: toGatewayAccount(account),
+  });
+  return {
+    channel: "qqbot" as const,
+    messageId: result.messageId ?? "",
+    receipt: createQQBotSendReceipt({
+      messageId: result.messageId,
+      target: params.to,
+      kind: "media",
+    }),
+    meta: result.error ? { error: result.error } : undefined,
+  };
+}
+
+function toQQBotMessageSendResult(result: Awaited<ReturnType<typeof sendQQBotText>>) {
+  return {
+    messageId: result.messageId,
+    receipt: result.receipt,
+  } satisfies ChannelMessageSendResult;
+}
+
+const qqbotMessageAdapter = defineChannelMessageAdapter({
+  id: "qqbot",
+  durableFinal: {
+    capabilities: {
+      text: true,
+      media: true,
+      replyTo: true,
+    },
+  },
+  send: {
+    text: async (ctx) =>
+      toQQBotMessageSendResult(
+        await sendQQBotText({
+          cfg: ctx.cfg,
+          to: ctx.to,
+          text: ctx.text,
+          accountId: ctx.accountId,
+          replyToId: ctx.replyToId,
+        }),
+      ),
+    media: async (ctx) =>
+      toQQBotMessageSendResult(
+        await sendQQBotMedia({
+          cfg: ctx.cfg,
+          to: ctx.to,
+          text: ctx.text,
+          mediaUrl: ctx.mediaUrl,
+          accountId: ctx.accountId,
+          replyToId: ctx.replyToId,
+        }),
+      ),
+  },
+});
+
+const EXEC_APPROVAL_COMMAND_RE =
+  /\/approve(?:@[^\s]+)?\s+[A-Za-z0-9][A-Za-z0-9._:-]*\s+(?:allow-once|allow-always|always|deny)\b/i;
+
+function persistAccountCredentialSnapshot(account: ResolvedQQBotAccount): void {
+  if (account.appId && account.clientSecret) {
+    saveCredentialBackup(account.accountId, account.appId, account.clientSecret);
+  }
+}
+
+function shouldSuppressLocalQQBotApprovalPrompt(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  payload: { text?: string; channelData?: unknown };
+  hint?: { kind: "approval-pending" | "approval-resolved"; approvalKind: "exec" | "plugin" };
+}): boolean {
+  if (params.hint?.kind !== "approval-pending" || params.hint.approvalKind !== "exec") {
+    return false;
+  }
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  if (!account.enabled || account.secretSource === "none") {
+    return false;
+  }
+  if (getExecApprovalReplyMetadata(params.payload as never)) {
+    return true;
+  }
+  const text = typeof params.payload.text === "string" ? params.payload.text : "";
+  return EXEC_APPROVAL_COMMAND_RE.test(text);
+}
+
+export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
+  id: "qqbot",
+  setupWizard: qqbotSetupWizard,
+  meta: {
+    ...qqbotMeta,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    reactions: false,
+    threads: false,
+    blockStreaming: true,
+  },
+  reload: { configPrefixes: ["channels.qqbot"] },
+  configSchema: qqbotChannelConfigSchema,
+  config: {
+    ...qqbotConfigAdapter,
+    /**
+     * Treat an account as configured when either the live config has
+     * credentials OR a recoverable credential backup exists. This mirrors
+     * the standalone plugin and lets the gateway survive a hot upgrade
+     * that wiped autobot.json mid-flight.
+     */
+    isConfigured: (account: ResolvedQQBotAccount | undefined) => {
+      if (qqbotConfigAdapter.isConfigured(account)) {
+        return true;
+      }
+      if (!account) {
+        return false;
+      }
+      const backup = loadCredentialBackup(account.accountId);
+      return Boolean(backup?.appId && backup?.clientSecret);
+    },
+  },
+  setup: {
+    ...qqbotSetupAdapterShared,
+  },
+  approvalCapability: getQQBotApprovalCapability(),
+  message: qqbotMessageAdapter,
+  messaging: {
+    targetPrefixes: ["qqbot"],
+    /** Normalize common QQ Bot target formats into the canonical qqbot:... form. */
+    normalizeTarget: coreNormalizeTarget,
+    targetResolver: {
+      /** Return true when the id looks like a QQ Bot target. */
+      looksLikeId: looksLikeQQBotTarget,
+      hint: "QQ Bot target format: qqbot:c2c:openid (direct) or qqbot:group:groupid (group)",
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    chunker: (text, limit) => getQQBotRuntime().channel.text.chunkMarkdownText(text, limit),
+    chunkerMode: "markdown",
+    textChunkLimit: 5000,
+    shouldSuppressLocalPayloadPrompt: ({ cfg, accountId, payload, hint }) =>
+      shouldSuppressLocalQQBotApprovalPrompt({
+        cfg,
+        accountId,
+        payload,
+        hint,
+      }),
+    sendText: async ({ to, text, accountId, replyToId, cfg }) =>
+      await sendQQBotText({
+        cfg,
+        to,
+        text,
+        accountId,
+        replyToId,
+      }),
+    sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) =>
+      await sendQQBotMedia({
+        cfg,
+        to,
+        text,
+        mediaUrl,
+        accountId,
+        replyToId,
+      }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      let { account, cfg } = ctx;
+      const { abortSignal, log } = ctx;
+
+      // Recover credentials from the per-account backup if the live
+      // config is missing appId/secret (e.g. a hot-upgrade wiped
+      // autobot.json). We only restore when both fields are empty so a
+      // user's intentional clear isn't silently undone.
+      if (!account.appId || !account.clientSecret) {
+        const backup = loadCredentialBackup(account.accountId);
+        if (backup?.appId && backup?.clientSecret) {
+          try {
+            const nextCfg = applyQQBotAccountConfig(cfg, account.accountId, {
+              appId: backup.appId,
+              clientSecret: backup.clientSecret,
+            });
+            await writeAutoBotConfigThroughRuntime(getQQBotRuntime(), nextCfg);
+            cfg = nextCfg;
+            account = resolveQQBotAccount(nextCfg, account.accountId);
+            log?.info(
+              `[qqbot:${account.accountId}] Restored credentials from backup (appId=${account.appId})`,
+            );
+          } catch (err) {
+            log?.error(
+              `[qqbot:${account.accountId}] Failed to restore credentials from backup: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+        }
+      }
+
+      // Serialize the dynamic import so concurrent multi-account startups
+      // do not hit an ESM circular-dependency race where the gateway chunk's
+      // transitive imports have not finished evaluating yet.
+      const { startGateway } = await loadGatewayModule();
+
+      log?.info(
+        `[qqbot:${account.accountId}] Starting gateway — appId=${account.appId}, enabled=${account.enabled}, name=${account.name ?? "unnamed"}`,
+      );
+
+      await startGateway({
+        account,
+        abortSignal,
+        cfg,
+        log,
+        channelRuntime: ctx.channelRuntime as GatewayContext["channelRuntime"],
+        onReady: () => {
+          log?.info(`[qqbot:${account.accountId}] Gateway ready`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          // Snapshot credentials so we can recover from the next hot
+          // upgrade that might wipe autobot.json mid-flight.
+          persistAccountCredentialSnapshot(account);
+        },
+        onResumed: () => {
+          log?.info(`[qqbot:${account.accountId}] Gateway resumed`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            connected: true,
+            lastConnectedAt: Date.now(),
+          });
+          persistAccountCredentialSnapshot(account);
+        },
+        onError: (error) => {
+          log?.error(`[qqbot:${account.accountId}] Gateway error: ${error.message}`);
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            lastError: error.message,
+          });
+        },
+      });
+    },
+    logoutAccount: async ({ accountId, cfg }) => {
+      const { nextCfg, cleared, changed } = clearAccountCredentials(
+        cfg as unknown as Record<string, unknown>,
+        accountId,
+      );
+
+      if (changed) {
+        await writeAutoBotConfigThroughRuntime(getQQBotRuntime(), nextCfg as AutoBotConfig);
+      }
+
+      const resolved = resolveQQBotAccount((changed ? nextCfg : cfg) as AutoBotConfig, accountId);
+      const loggedOut = resolved.secretSource === "none";
+      const envToken = Boolean(process.env.QQBOT_CLIENT_SECRET);
+
+      return { ok: true, cleared, envToken, loggedOut };
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      connected: false,
+      lastConnectedAt: null,
+      lastError: null,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      tokenSource: snapshot.tokenSource ?? "none",
+      running: snapshot.running ?? false,
+      connected: snapshot.connected ?? false,
+      lastConnectedAt: snapshot.lastConnectedAt ?? null,
+      lastError: snapshot.lastError ?? null,
+    }),
+    buildAccountSnapshot: ({ account, runtime }) => ({
+      accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
+      name: account?.name,
+      enabled: account?.enabled ?? false,
+      configured: Boolean(account?.appId && account?.clientSecret),
+      tokenSource: account?.secretSource,
+      running: runtime?.running ?? false,
+      connected: runtime?.connected ?? false,
+      lastConnectedAt: runtime?.lastConnectedAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+};

package/src/config-schema.ts

@@ -0,0 +1,84 @@
+import {
+  AllowFromListSchema,
+  buildChannelConfigSchema,
+} from "autobot/plugin-sdk/channel-config-schema";
+import { buildSecretInputSchema } from "autobot/plugin-sdk/secret-input";
+import { z } from "zod";
+
+const AudioFormatPolicySchema = z
+  .object({
+    sttDirectFormats: z.array(z.string()).optional(),
+    uploadDirectFormats: z.array(z.string()).optional(),
+    transcodeEnabled: z.boolean().optional(),
+  })
+  .optional();
+
+const QQBotSttSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    provider: z.string().optional(),
+    baseUrl: z.string().optional(),
+    apiKey: z.string().optional(),
+    model: z.string().optional(),
+  })
+  .strict()
+  .optional();
+
+/** When `true`, same as `mode: "partial"` and `c2cStreamApi: true` for C2C. Object form kept for legacy configs. */
+const QQBotStreamingSchema = z
+  .union([
+    z.boolean(),
+    z
+      .object({
+        /** "partial" (default) enables block streaming; "off" disables it. */
+        mode: z.enum(["off", "partial"]).default("partial"),
+        /** @deprecated Prefer `streaming: true`. */
+        c2cStreamApi: z.boolean().optional(),
+      })
+      .passthrough(),
+  ])
+  .optional();
+
+const QQBotExecApprovalsSchema = z
+  .object({
+    enabled: z.union([z.boolean(), z.literal("auto")]).optional(),
+    approvers: z.array(z.string()).optional(),
+    agentFilter: z.array(z.string()).optional(),
+    sessionFilter: z.array(z.string()).optional(),
+    target: z.enum(["dm", "channel", "both"]).optional(),
+  })
+  .strict()
+  .optional();
+
+const QQBotDmPolicySchema = z.enum(["open", "allowlist", "disabled"]).optional();
+const QQBotGroupPolicySchema = z.enum(["open", "allowlist", "disabled"]).optional();
+
+const QQBotAccountSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    name: z.string().optional(),
+    appId: z.string().optional(),
+    clientSecret: buildSecretInputSchema().optional(),
+    clientSecretFile: z.string().optional(),
+    allowFrom: AllowFromListSchema,
+    groupAllowFrom: AllowFromListSchema,
+    dmPolicy: QQBotDmPolicySchema,
+    groupPolicy: QQBotGroupPolicySchema,
+    systemPrompt: z.string().optional(),
+    markdownSupport: z.boolean().optional(),
+    voiceDirectUploadFormats: z.array(z.string()).optional(),
+    audioFormatPolicy: AudioFormatPolicySchema,
+    urlDirectUpload: z.boolean().optional(),
+    upgradeUrl: z.string().optional(),
+    upgradeMode: z.enum(["doc", "hot-reload"]).optional(),
+    streaming: QQBotStreamingSchema,
+    execApprovals: QQBotExecApprovalsSchema,
+  })
+  .passthrough();
+
+export const QQBotConfigSchema = QQBotAccountSchema.extend({
+  stt: QQBotSttSchema,
+  accounts: z.object({}).catchall(QQBotAccountSchema.passthrough()).optional(),
+  defaultAccount: z.string().optional(),
+}).passthrough();
+export const qqbotChannelConfigSchema = buildChannelConfigSchema(QQBotConfigSchema);

package/src/engine/access/index.ts

@@ -0,0 +1,2 @@
+export { createQQBotSenderMatcher, normalizeQQBotAllowFrom } from "./sender-match.js";
+export { type QQBotDmPolicy, type QQBotGroupPolicy } from "./types.js";

package/src/engine/access/resolve-policy.ts

@@ -0,0 +1,30 @@
+import type { QQBotDmPolicy, QQBotGroupPolicy } from "./types.js";
+
+export interface EffectivePolicyInput {
+  allowFrom?: Array<string | number> | null;
+  groupAllowFrom?: Array<string | number> | null;
+  dmPolicy?: QQBotDmPolicy | null;
+  groupPolicy?: QQBotGroupPolicy | null;
+}
+
+function hasRealRestriction(list: Array<string | number> | null | undefined): boolean {
+  if (!list || list.length === 0) {
+    return false;
+  }
+  return !list.every((entry) => String(entry).trim() === "*");
+}
+
+export function resolveQQBotEffectivePolicies(input: EffectivePolicyInput): {
+  dmPolicy: QQBotDmPolicy;
+  groupPolicy: QQBotGroupPolicy;
+} {
+  const allowFromRestricted = hasRealRestriction(input.allowFrom);
+  const groupAllowFromRestricted = hasRealRestriction(input.groupAllowFrom);
+
+  const dmPolicy: QQBotDmPolicy = input.dmPolicy ?? (allowFromRestricted ? "allowlist" : "open");
+
+  const groupPolicy: QQBotGroupPolicy =
+    input.groupPolicy ?? (groupAllowFromRestricted || allowFromRestricted ? "allowlist" : "open");
+
+  return { dmPolicy, groupPolicy };
+}

package/src/engine/access/sender-match.ts

@@ -0,0 +1,55 @@
+/**
+ * QQBot sender normalization and allowlist matching.
+ *
+ * Keeps QQ-specific quirks (the `qqbot:` prefix, uppercase-insensitive
+ * comparison) localized to this module so the policy engine itself can
+ * stay channel-agnostic.
+ */
+
+/** Normalize a single entry (openid): strip `qqbot:` prefix, uppercase, trim. */
+export function normalizeQQBotSenderId(raw: unknown): string {
+  if (typeof raw !== "string" && typeof raw !== "number") {
+    return "";
+  }
+  return String(raw)
+    .trim()
+    .replace(/^qqbot:/i, "")
+    .toUpperCase();
+}
+
+/** Normalize an entire allowFrom list, dropping empty entries. */
+export function normalizeQQBotAllowFrom(list: Array<string | number> | undefined | null): string[] {
+  if (!list || list.length === 0) {
+    return [];
+  }
+  const out: string[] = [];
+  for (const entry of list) {
+    const normalized = normalizeQQBotSenderId(entry);
+    if (normalized) {
+      out.push(normalized);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a matcher closure suitable for passing to the policy engine's
+ * `isSenderAllowed` callback. The caller supplies the sender once, and
+ * the returned function can be invoked against different allowlists
+ * (DM allowlist vs group allowlist) without repeating normalization.
+ */
+export function createQQBotSenderMatcher(senderId: string): (allowFrom: string[]) => boolean {
+  const normalizedSender = normalizeQQBotSenderId(senderId);
+  return (allowFrom: string[]) => {
+    if (allowFrom.length === 0) {
+      return false;
+    }
+    if (allowFrom.includes("*")) {
+      return true;
+    }
+    if (!normalizedSender) {
+      return false;
+    }
+    return allowFrom.some((entry) => normalizeQQBotSenderId(entry) === normalizedSender);
+  };
+}

package/src/engine/access/types.ts

@@ -0,0 +1,2 @@
+export type QQBotDmPolicy = "open" | "allowlist" | "disabled";
+export type QQBotGroupPolicy = "open" | "allowlist" | "disabled";