@gakr-gakr/qqbot 0.1.0

package/src/exec-approvals.ts

@@ -0,0 +1,237 @@
+import { resolveApprovalApprovers } from "autobot/plugin-sdk/approval-auth-runtime";
+import {
+  createChannelExecApprovalProfile,
+  isChannelExecApprovalClientEnabledFromConfig,
+  matchesApprovalRequestFilters,
+} from "autobot/plugin-sdk/approval-client-runtime";
+import { resolveApprovalRequestChannelAccountId } from "autobot/plugin-sdk/approval-native-runtime";
+import type {
+  ExecApprovalRequest,
+  PluginApprovalRequest,
+} from "autobot/plugin-sdk/approval-runtime";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { normalizeAccountId } from "autobot/plugin-sdk/routing";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "autobot/plugin-sdk/string-coerce-runtime";
+import { listQQBotAccountIds, resolveQQBotAccount } from "./bridge/config.js";
+import type { QQBotExecApprovalConfig } from "./types.js";
+
+function normalizeApproverId(value: string | number): string | undefined {
+  const trimmed = normalizeOptionalString(String(value));
+  return trimmed || undefined;
+}
+
+export function resolveQQBotExecApprovalConfig(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): QQBotExecApprovalConfig | undefined {
+  const account = resolveQQBotAccount(params.cfg, params.accountId);
+  const config = account.config.execApprovals;
+  if (!config) {
+    return undefined;
+  }
+  return {
+    ...config,
+    enabled: account.enabled && account.secretSource !== "none" ? config.enabled : false,
+  };
+}
+
+function getQQBotExecApprovalApprovers(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+}): string[] {
+  const accountConfig = resolveQQBotAccount(params.cfg, params.accountId).config;
+  return resolveApprovalApprovers({
+    explicit: resolveQQBotExecApprovalConfig(params)?.approvers,
+    allowFrom: accountConfig.allowFrom,
+    normalizeApprover: normalizeApproverId,
+  });
+}
+
+function countQQBotExecApprovalEligibleAccounts(params: {
+  cfg: AutoBotConfig;
+  request: ExecApprovalRequest | PluginApprovalRequest;
+}): number {
+  return listQQBotAccountIds(params.cfg).filter((accountId) => {
+    const account = resolveQQBotAccount(params.cfg, accountId);
+    if (!account.enabled || account.secretSource === "none") {
+      return false;
+    }
+    const config = resolveQQBotExecApprovalConfig({
+      cfg: params.cfg,
+      accountId,
+    });
+    return (
+      isChannelExecApprovalClientEnabledFromConfig({
+        enabled: config?.enabled,
+        approverCount: getQQBotExecApprovalApprovers({ cfg: params.cfg, accountId }).length,
+      }) &&
+      matchesApprovalRequestFilters({
+        request: params.request.request,
+        agentFilter: config?.agentFilter,
+        sessionFilter: config?.sessionFilter,
+        fallbackAgentIdFromSessionKey: true,
+      })
+    );
+  }).length;
+}
+
+function matchesQQBotRequestAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  request: ExecApprovalRequest | PluginApprovalRequest;
+}): boolean {
+  const turnSourceChannel = normalizeLowercaseStringOrEmpty(
+    params.request.request.turnSourceChannel,
+  );
+  const boundAccountId = resolveApprovalRequestChannelAccountId({
+    cfg: params.cfg,
+    request: params.request,
+    channel: "qqbot",
+  });
+  if (turnSourceChannel && turnSourceChannel !== "qqbot" && !boundAccountId) {
+    return (
+      countQQBotExecApprovalEligibleAccounts({
+        cfg: params.cfg,
+        request: params.request,
+      }) <= 1
+    );
+  }
+  return (
+    !boundAccountId ||
+    !params.accountId ||
+    normalizeAccountId(boundAccountId) === normalizeAccountId(params.accountId)
+  );
+}
+
+/**
+ * Count QQBot accounts that could actually deliver a native approval
+ * message — i.e. accounts that are enabled and have resolvable secrets.
+ * Disabled or unconfigured accounts never spawn a handler, so they
+ * must not contribute to the single-account shortcut in the fallback
+ * ownership check below.
+ */
+function countQQBotFallbackEligibleAccounts(cfg: AutoBotConfig): number {
+  return listQQBotAccountIds(cfg).filter((accountId) => {
+    const account = resolveQQBotAccount(cfg, accountId);
+    return account.enabled && account.secretSource !== "none";
+  }).length;
+}
+
+/**
+ * Fallback account-ownership check — applied when `execApprovals` is NOT
+ * configured for any QQBot account. In this mode every enabled account
+ * handler would otherwise race to deliver the same approval to its own
+ * openid namespace, so we must enforce per-account isolation.
+ *
+ * Rules:
+ *   - If the request carries a bound account (via `turnSourceAccountId`
+ *     or session binding), only the handler whose `accountId` matches it
+ *     delivers the approval. This is strict: a handler with an unknown
+ *     `accountId` (null/undefined) must not claim a bound request.
+ *   - If no account is bound, only deliver when there is a single
+ *     *eligible* QQBot account (enabled + secret resolved). Disabled or
+ *     unconfigured accounts never deliver anyway, so they shouldn't
+ *     block the remaining single account from handling the approval.
+ *     Multiple eligible accounts cannot safely race because openids are
+ *     account-scoped — cross-account delivery hits the QQ Bot API with
+ *     a mismatched token and fails.
+ */
+function matchesQQBotFallbackRequestAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  request: ExecApprovalRequest | PluginApprovalRequest;
+}): boolean {
+  const boundAccountId = resolveApprovalRequestChannelAccountId({
+    cfg: params.cfg,
+    request: params.request,
+    channel: "qqbot",
+  });
+
+  if (boundAccountId) {
+    if (!params.accountId) {
+      return false;
+    }
+    return normalizeAccountId(boundAccountId) === normalizeAccountId(params.accountId);
+  }
+
+  return countQQBotFallbackEligibleAccounts(params.cfg) <= 1;
+}
+
+/**
+ * Minimal structural shape required to evaluate per-account ownership.
+ *
+ * The SDK types (`ExecApprovalRequest` / `PluginApprovalRequest`) and the
+ * channel-local approval request types (see `engine/approval/index.ts`)
+ * share the same logical fields but differ on bookkeeping metadata
+ * (e.g. `createdAtMs`), so we accept any object exposing the relevant
+ * routing fields. Consumers can pass either flavor safely.
+ */
+type QQBotApprovalAccountOwnershipRequest = {
+  request: {
+    sessionKey?: string | null;
+    turnSourceChannel?: string | null;
+    turnSourceTo?: string | null;
+    turnSourceAccountId?: string | null;
+  };
+};
+
+/**
+ * Unified per-account ownership check used by both the profile and
+ * fallback approval paths. Dispatches to the profile rules when the
+ * current account has `execApprovals` configured, otherwise uses the
+ * fallback rules.
+ *
+ * This is the single source of truth for "does this QQBot handler own
+ * this approval request?" and is consumed by both the capability
+ * gate (shouldHandle) and the lazy native runtime adapter.
+ */
+export function matchesQQBotApprovalAccount(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  request: QQBotApprovalAccountOwnershipRequest;
+}): boolean {
+  const normalized = {
+    cfg: params.cfg,
+    accountId: params.accountId,
+    request: params.request as unknown as ExecApprovalRequest | PluginApprovalRequest,
+  };
+  if (resolveQQBotExecApprovalConfig(normalized) !== undefined) {
+    return matchesQQBotRequestAccount(normalized);
+  }
+  return matchesQQBotFallbackRequestAccount(normalized);
+}
+
+const qqbotExecApprovalProfile = createChannelExecApprovalProfile({
+  resolveConfig: resolveQQBotExecApprovalConfig,
+  resolveApprovers: getQQBotExecApprovalApprovers,
+  matchesRequestAccount: matchesQQBotRequestAccount,
+  fallbackAgentIdFromSessionKey: true,
+  requireClientEnabledForLocalPromptSuppression: false,
+});
+
+export const isQQBotExecApprovalClientEnabled = qqbotExecApprovalProfile.isClientEnabled;
+export const isQQBotExecApprovalApprover = qqbotExecApprovalProfile.isApprover;
+export const isQQBotExecApprovalAuthorizedSender = qqbotExecApprovalProfile.isAuthorizedSender;
+export const shouldHandleQQBotExecApprovalRequest = qqbotExecApprovalProfile.shouldHandleRequest;
+
+export function authorizeQQBotApprovalAction(params: {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+  senderId?: string | null;
+  approvalKind: "exec" | "plugin";
+}): { authorized: boolean; reason?: string } {
+  if (resolveQQBotExecApprovalConfig(params) === undefined) {
+    return { authorized: true };
+  }
+
+  const authorized =
+    params.approvalKind === "plugin"
+      ? isQQBotExecApprovalApprover(params)
+      : isQQBotExecApprovalAuthorizedSender(params);
+  return authorized
+    ? { authorized: true }
+    : { authorized: false, reason: "You are not authorized to approve this request." };
+}

package/src/qqbot-test-support.ts

@@ -0,0 +1,29 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+
+export function makeQqbotSecretRefConfig(): AutoBotConfig {
+  return {
+    channels: {
+      qqbot: {
+        appId: "123456",
+        clientSecret: {
+          source: "env",
+          provider: "default",
+          id: "QQBOT_CLIENT_SECRET",
+        },
+      },
+    },
+  } as AutoBotConfig;
+}
+
+export function makeQqbotDefaultAccountConfig(): AutoBotConfig {
+  return {
+    channels: {
+      qqbot: {
+        defaultAccount: "bot2",
+        accounts: {
+          bot2: { appId: "123456" },
+        },
+      },
+    },
+  } as AutoBotConfig;
+}

package/src/secret-contract.ts

@@ -0,0 +1,82 @@
+import {
+  collectConditionalChannelFieldAssignments,
+  getChannelSurface,
+  hasConfiguredSecretInputValue,
+  type ResolverContext,
+  type SecretDefaults,
+  type SecretTargetRegistryEntry,
+} from "autobot/plugin-sdk/channel-secret-basic-runtime";
+
+const DEFAULT_ACCOUNT_ID = "default";
+
+export const secretTargetRegistryEntries = [
+  {
+    id: "channels.qqbot.accounts.*.clientSecret",
+    targetType: "channels.qqbot.accounts.*.clientSecret",
+    configFile: "autobot.json",
+    pathPattern: "channels.qqbot.accounts.*.clientSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+  {
+    id: "channels.qqbot.clientSecret",
+    targetType: "channels.qqbot.clientSecret",
+    configFile: "autobot.json",
+    pathPattern: "channels.qqbot.clientSecret",
+    secretShape: "secret_input",
+    expectedResolvedValue: "string",
+    includeInPlan: true,
+    includeInConfigure: true,
+    includeInAudit: true,
+  },
+] satisfies SecretTargetRegistryEntry[];
+
+function hasTopLevelAppId(qqbot: Record<string, unknown>): boolean {
+  if (typeof qqbot.appId === "string") {
+    return qqbot.appId.trim().length > 0;
+  }
+  return typeof qqbot.appId === "number";
+}
+
+export function collectRuntimeConfigAssignments(params: {
+  config: { channels?: Record<string, unknown> };
+  defaults?: SecretDefaults;
+  context: ResolverContext;
+}): void {
+  const resolved = getChannelSurface(params.config, "qqbot");
+  if (!resolved) {
+    return;
+  }
+
+  const { channel: qqbot, surface } = resolved;
+  const hasExplicitDefaultAccount = surface.accounts.some(
+    ({ accountId }) => accountId === DEFAULT_ACCOUNT_ID,
+  );
+
+  collectConditionalChannelFieldAssignments({
+    channelKey: "qqbot",
+    field: "clientSecret",
+    channel: qqbot,
+    surface,
+    defaults: params.defaults,
+    context: params.context,
+    topLevelActiveWithoutAccounts: true,
+    topLevelInheritedAccountActive: ({ accountId, account, enabled }) => {
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return enabled && !hasConfiguredSecretInputValue(account.clientSecret, params.defaults);
+      }
+      return !hasExplicitDefaultAccount && hasTopLevelAppId(qqbot);
+    },
+    accountActive: ({ enabled }) => enabled,
+    topInactiveReason: "no enabled QQ Bot default surface uses this top-level clientSecret.",
+    accountInactiveReason: "QQ Bot account is disabled.",
+  });
+}
+
+export const channelSecrets = {
+  secretTargetRegistryEntries,
+  collectRuntimeConfigAssignments,
+};

package/src/types.ts

@@ -0,0 +1,210 @@
+import type { SecretInput } from "autobot/plugin-sdk/secret-input";
+import type { QQBotDmPolicy, QQBotGroupPolicy } from "./engine/access/index.js";
+
+export type { QQBotDmPolicy, QQBotGroupPolicy };
+
+/** QQ Bot base config. */
+export interface QQBotConfig {
+  appId: string;
+  clientSecret?: SecretInput;
+  clientSecretFile?: string;
+}
+
+/** Resolved QQ Bot account config used at runtime. */
+export interface ResolvedQQBotAccount {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  appId: string;
+  clientSecret: string;
+  secretSource: "config" | "file" | "env" | "none";
+  /** Additional system prompt text. */
+  systemPrompt?: string;
+  /** Whether markdown output is enabled. Defaults to true. */
+  markdownSupport: boolean;
+  config: QQBotAccountConfig;
+}
+
+/** QQBot-native exec approval delivery + approver authorization. */
+export interface QQBotExecApprovalConfig {
+  enabled?: boolean | "auto";
+  approvers?: string[];
+  agentFilter?: string[];
+  sessionFilter?: string[];
+  target?: "dm" | "channel" | "both";
+}
+
+/** QQ Bot account config from user settings. */
+export interface QQBotAccountConfig {
+  enabled?: boolean;
+  name?: string;
+  appId?: string;
+  clientSecret?: SecretInput;
+  clientSecretFile?: string;
+  /**
+   * Sender allowlist for direct-message access control and command
+   * authorization. Entries accept raw openids, `qqbot:OPENID` prefixed
+   * form, and the `"*"` wildcard. Matching is case-insensitive.
+   *
+   * Semantics depend on {@link dmPolicy}:
+   *   - `dmPolicy="open"` (default when allowFrom is empty or contains `"*"`)
+   *     — everyone can DM the bot; the list only influences command gating.
+   *   - `dmPolicy="allowlist"` (default when a non-wildcard list is configured)
+   *     — only listed openids may DM the bot; other DMs are dropped.
+   *   - `dmPolicy="disabled"` — all DMs are dropped regardless of this list.
+   *
+   * For group access, see {@link groupAllowFrom} / {@link groupPolicy}.
+   */
+  allowFrom?: string[];
+  /**
+   * Group-scoped sender allowlist. If omitted, group access falls back to
+   * {@link allowFrom}. Set explicitly when the group whitelist needs to
+   * differ from the DM whitelist.
+   */
+  groupAllowFrom?: string[];
+  /**
+   * DM access policy. Defaults:
+   *   - omitted + allowFrom empty/wildcard → `"open"`
+   *   - omitted + allowFrom non-wildcard   → `"allowlist"`
+   */
+  dmPolicy?: QQBotDmPolicy;
+  /**
+   * Group access policy. Defaults mirror {@link dmPolicy}: if either
+   * `groupAllowFrom` or `allowFrom` has a non-wildcard entry the policy
+   * is `"allowlist"`, otherwise `"open"`.
+   */
+  groupPolicy?: QQBotGroupPolicy;
+  /** Optional system prompt prepended to user messages. */
+  systemPrompt?: string;
+  /** Whether markdown output is enabled. Defaults to true. */
+  markdownSupport?: boolean;
+  /** QQBot-native exec approval delivery + approver authorization. */
+  execApprovals?: QQBotExecApprovalConfig;
+  /**
+   * @deprecated Use audioFormatPolicy.uploadDirectFormats instead.
+   * Legacy list of formats that can upload directly without SILK conversion.
+   */
+  voiceDirectUploadFormats?: string[];
+  /**
+   * Audio format policy covering inbound STT and outbound upload behavior.
+   */
+  audioFormatPolicy?: AudioFormatPolicy;
+  /**
+   * Whether public URLs should be uploaded to QQ directly. Defaults to true.
+   */
+  urlDirectUpload?: boolean;
+  /**
+   * Upgrade guide URL returned by `/bot-upgrade`.
+   */
+  upgradeUrl?: string;
+  /**
+   * Upgrade command mode.
+   * - "doc": show an upgrade guide link
+   * - "hot-reload": run an in-place npm update flow
+   */
+  upgradeMode?: "doc" | "hot-reload";
+  /**
+   * Block streaming + optional QQ C2C official stream API.
+   * - `true`: same as `mode: "partial"` and `c2cStreamApi: true` (recommended).
+   * - `false` / omitted: no official C2C stream for this account (see object form for fine control).
+   * - Object (legacy / advanced): `mode` "partial" | "off", `c2cStreamApi` for C2C `/stream_messages`.
+   */
+  streaming?:
+    | boolean
+    | {
+        mode?: "off" | "partial";
+        /** @deprecated Prefer `streaming: true`. */
+        c2cStreamApi?: boolean;
+      };
+}
+
+/** Audio format policy controlling which formats can skip transcoding. */
+export interface AudioFormatPolicy {
+  /**
+   * Formats supported directly by the STT provider.
+   */
+  sttDirectFormats?: string[];
+  /**
+   * Formats QQ accepts directly for outbound uploads.
+   */
+  uploadDirectFormats?: string[];
+  /**
+   * Whether outbound audio transcoding is enabled. Defaults to true.
+   */
+  transcodeEnabled?: boolean;
+}
+
+/** Rich-media attachment metadata. */
+export interface MessageAttachment {
+  content_type: string;
+  filename?: string;
+  height?: number;
+  width?: number;
+  size?: number;
+  url: string;
+  voice_wav_url?: string;
+  asr_refer_text?: string;
+}
+
+/** C2C message event payload. */
+export interface C2CMessageEvent {
+  author: {
+    id: string;
+    union_openid: string;
+    user_openid: string;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  message_scene?: {
+    source: string;
+    /** ext can contain ref_msg_idx and msg_idx values. */
+    ext?: string[];
+  };
+  attachments?: MessageAttachment[];
+}
+
+/** Guild @-message event payload. */
+export interface GuildMessageEvent {
+  id: string;
+  channel_id: string;
+  guild_id: string;
+  content: string;
+  timestamp: string;
+  author: {
+    id: string;
+    username?: string;
+    bot?: boolean;
+  };
+  member?: {
+    nick?: string;
+    joined_at?: string;
+  };
+  attachments?: MessageAttachment[];
+}
+
+/** Group @-message event payload. */
+export interface GroupMessageEvent {
+  author: {
+    id: string;
+    member_openid: string;
+  };
+  content: string;
+  id: string;
+  timestamp: string;
+  group_id: string;
+  group_openid: string;
+  message_scene?: {
+    source: string;
+    ext?: string[];
+  };
+  attachments?: MessageAttachment[];
+}
+
+/** WebSocket event payload. */
+export interface WSPayload {
+  op: number;
+  d?: unknown;
+  s?: number;
+  t?: string;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}