@zhin.js/adapter-qq 1.0.84 → 1.1.2

package/src/qq-runtime-state.ts

@@ -0,0 +1,51 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定 / 待选 botKind 流程。由 plugin.ts setup() provide，
+ * adapter create 与 commands / middleware 通过 use(qqRuntimeStateToken) 共享。
+ */
+import { createToken } from 'zhin.js';
+
+export interface QqRunningEndpoint {
+  id: string;
+  mode: string;
+}
+
+export interface QqBindFlowHandle {
+  /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
+  id?: string;
+  stop: () => void;
+}
+
+/**
+ * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
+ * （提前写 .env 会触发 HMR，冲掉 pending。）
+ */
+export interface QqPendingBotKind {
+  readonly endpointId: string;
+  readonly appId: string;
+  readonly appSecret: string;
+  /** 发起 add 的会话键；仅同会话回复可完成选择 */
+  readonly sessionKey: string;
+}
+
+export interface QqRuntimeState {
+  /** 当前 generation 已成功创建的 endpoint（id → 描述） */
+  readonly endpoints: Map<string, QqRunningEndpoint>;
+  /** 全局单例：同一时间只允许一个扫码绑定流程 */
+  bindFlow: QqBindFlowHandle | null;
+  /** 扫码完成后等待 botKind 选择（凭据仅在内存） */
+  pendingBotKind: QqPendingBotKind | null;
+}
+
+export function createQqRuntimeState(): QqRuntimeState {
+  return {
+    endpoints: new Map(),
+    bindFlow: null,
+    pendingBotKind: null,
+  };
+}
+
+export const qqRuntimeStateToken = createToken<QqRuntimeState>(
+  'zhin.qq.runtime-state',
+  'QQ adapter runtime state (running endpoints + bind flow singleton)',
+);

package/src/side-event-dispatch.ts

@@ -0,0 +1,140 @@
+import { receiveOneBotLikeSideEvent, type OneBotLikeRawEvent } from '@zhin.js/core';
+import type { EndpointEventEmitter } from 'zhin.js/adapter';
+import { formatCompact, type getAdapterLogger } from '@zhin.js/logger';
+import type { ApproveJoinRequestOptions } from 'qq-official-bot';
+
+export interface QqSideEventCaller {
+  approveGroupJoinRequest?(
+    groupId: string,
+    userId: string,
+    options: ApproveJoinRequestOptions,
+  ): Promise<unknown>;
+}
+
+export function bindQqBotSideEvents(
+  bot: { on(event: string, listener: (...args: unknown[]) => void): void },
+  dispatch: (eventName: string, raw: unknown) => void,
+): void {
+  // qq-official-bot emits every dotted prefix. Listening at `notice` once avoids
+  // dispatching e.g. notice.group.member.increase three times.
+  bot.on('notice', (raw) => dispatch(resolveQqSideEventName(raw), raw));
+}
+
+function resolveQqSideEventName(raw: unknown): string {
+  if (!raw || typeof raw !== 'object') return 'notice';
+  const record = raw as Record<string, unknown>;
+  return ['notice', record.notice_type, record.sub_type]
+    .filter((part) => part != null && String(part) !== '')
+    .map(String)
+    .join('.');
+}
+
+function toOneBotLikeRaw(eventName: string, raw: unknown): OneBotLikeRawEvent | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const record = raw as Record<string, unknown>;
+  const asId = (value: unknown): string | number | undefined => {
+    if (typeof value === 'string' || typeof value === 'number') return value;
+    return undefined;
+  };
+  const asTime = (value: unknown): number => {
+    const n = typeof value === 'number' ? value : Number(value);
+    if (Number.isFinite(n) && n > 0) return n;
+    const date = typeof value === 'string' ? Date.parse(value) : Number.NaN;
+    return Number.isFinite(date) ? date : Date.now();
+  };
+  if (eventName === 'notice.group.join_request') {
+    return {
+      ...record,
+      post_type: 'request',
+      request_type: 'group',
+      flag: record.join_request_id != null ? String(record.join_request_id) : undefined,
+      user_id: asId(record.user_id),
+      group_id: asId(record.group_id),
+      comment: formatJoinRequestComment(record.verify_info),
+      time: asTime(record.time ?? record.timestamp ?? record.apply_at),
+    };
+  }
+  if (eventName.startsWith('notice.')) {
+    const memberChange = eventName.match(/^notice\.group(?:\.member)?\.(increase|decrease)$/);
+    const memberUserId = asId(record.user_id)
+      ?? asId((record.bot as { self_id?: unknown } | undefined)?.self_id);
+    return {
+      ...record,
+      post_type: 'notice',
+      notice_type: memberChange ? `group_${memberChange[1]}` : eventName.replace(/^notice\./, ''),
+      ...(memberChange && memberUserId != null ? { user_id: memberUserId } : {}),
+      time: asTime(record.time ?? record.timestamp),
+    };
+  }
+  return null;
+}
+
+function formatJoinRequestComment(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  if (!value || typeof value !== 'object') return undefined;
+  const verify = value as {
+    verify_message?: unknown;
+    review_qa_list?: Array<{ question?: unknown; answer?: unknown }>;
+  };
+  if (typeof verify.verify_message === 'string') return verify.verify_message;
+  if (!Array.isArray(verify.review_qa_list)) return undefined;
+  const lines = verify.review_qa_list.flatMap((item) => {
+    const question = typeof item?.question === 'string' ? item.question : '';
+    const answer = typeof item?.answer === 'string' ? item.answer : '';
+    return question || answer ? [`${question}${question && answer ? ': ' : ''}${answer}`] : [];
+  });
+  return lines.length > 0 ? lines.join('\n') : undefined;
+}
+
+export function receiveQqSideEvent(
+  emit: EndpointEventEmitter,
+  endpointKey: string,
+  caller: QqSideEventCaller,
+  eventName: string,
+  raw: unknown,
+  logger: ReturnType<typeof getAdapterLogger>,
+): void {
+  if (!emit) return;
+  const mapped = toOneBotLikeRaw(eventName, raw);
+  if (!mapped) return;
+  const isJoinRequest = eventName === 'notice.group.join_request';
+  const joinRaw = isJoinRequest && raw && typeof raw === 'object'
+    ? raw as { group_id?: string | number; user_id?: string | number; join_request_id?: string | number }
+    : undefined;
+  void receiveOneBotLikeSideEvent(emit, {
+    adapter: 'qq',
+    endpointKey,
+    platform: 'qq',
+    raw: mapped,
+    ...(isJoinRequest && caller.approveGroupJoinRequest && joinRaw ? {
+      approve: async (flag, remark) => {
+        await caller.approveGroupJoinRequest!(
+          String(joinRaw.group_id ?? ''),
+          String(joinRaw.user_id ?? ''),
+          {
+            op: 'approve',
+            join_request_id: String(joinRaw.join_request_id ?? flag),
+          },
+        );
+      },
+      reject: async (flag, reason) => {
+        await caller.approveGroupJoinRequest!(
+          String(joinRaw.group_id ?? ''),
+          String(joinRaw.user_id ?? ''),
+          {
+            op: 'decline',
+            join_request_id: String(joinRaw.join_request_id ?? flag),
+            ...(reason ? { reject_reason: reason } : {}),
+          },
+        );
+      },
+    } : {}),
+  }).catch((err) => {
+    logger.warn(formatCompact({
+      op: 'qq_side_event_failed',
+      endpoint: endpointKey,
+      event: eventName,
+      error: err instanceof Error ? err.message : String(err),
+    }));
+  });
+}

package/src/webhook.ts

@@ -0,0 +1,132 @@
+/**
+ * QQ HTTP webhook / middleware inbound via httpHostToken POST.
+ */
+import path from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Bot, ReceiverMode, type Sendable } from 'qq-official-bot';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+import type { ResolvedQqHttpConfig } from './protocol.js';
+import type { QqBotTransport } from './ws.js';
+
+const logger = getLogger('qq');
+
+export type QqHttpBotTransport = QqBotTransport & {
+  middleware: (ctx: unknown, next: () => Promise<void>) => Promise<unknown>;
+};
+
+export type CreateQqHttpBot = (config: ResolvedQqHttpConfig) => QqHttpBotTransport;
+
+export interface QqWebhookHandler {
+  readonly config: ResolvedQqHttpConfig;
+  getBot(): (QqHttpBotTransport & { middleware?: QqHttpBotTransport['middleware'] }) | null;
+}
+
+export function registerQqWebhookRoutes(
+  http: HttpHost,
+  handler: QqWebhookHandler,
+): HttpRouteRegistration[] {
+  const webhookPath = handler.config.webhookPath;
+  return [
+    http.route('POST', webhookPath, async (request, response) => {
+      await handleQqWebhookRequest(request, response, handler);
+    }, { summary: 'QQ webhook callback', tags: ['qq'] }),
+  ];
+}
+
+export async function handleQqWebhookRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  handler: QqWebhookHandler,
+): Promise<void> {
+  const bot = handler.getBot();
+  if (!bot?.middleware) {
+    response.writeHead(503, { 'Content-Type': 'text/plain' });
+    response.end('QQ receiver not ready');
+    return;
+  }
+  try {
+    // 不预消费请求流：库的验签必须基于原始字节（JSON.parse → JSON.stringify
+    // 会改变空白/转义/键序导致 401），body 留 undefined 让库自己读流；
+    // 预消费还会让非 JSON body 时库监听已结束的 end 事件而挂死。
+    await bot.middleware({
+      req: request,
+      res: response,
+      request: { body: undefined },
+    }, async () => undefined);
+  } catch (error) {
+    logger.error('QQ webhook error:', error);
+    if (!response.headersSent) {
+      response.writeHead(500, { 'Content-Type': 'text/plain' });
+      response.end('Internal Server Error');
+    }
+  }
+}
+
+export async function readRequestBodyText(request: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > 1_048_576) {
+      request.destroy();
+      throw new Error('Request body exceeds 1MB');
+    }
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export function defaultCreateHttpBot(config: ResolvedQqHttpConfig): QqHttpBotTransport {
+  const bot = new Bot({
+    appid: config.appid,
+    secret: config.secret,
+    mode: ReceiverMode.MIDDLEWARE,
+    platform: 'koa',
+    sandbox: config.sandbox,
+    dataDir: path.join(process.cwd(), 'data', 'qq'),
+    // 关闭内置 log4js，与 WebSocket 模式一致走 zhin adapter logger
+    logLevel: 'off',
+  } as never) as Bot<ReceiverMode.MIDDLEWARE, 'koa'> & QqBotTransport;
+
+  return {
+    api: bot,
+    start: () => bot.start().then(() => undefined),
+    stop: () => bot.stop().then(() => undefined),
+    on: (event, listener) => {
+      bot.on(event as never, listener as never);
+    },
+    removeAllListeners: () => {
+      bot.removeAllListeners(undefined as never);
+    },
+    sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message as Sendable),
+    sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message as Sendable),
+    sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message as Sendable),
+    sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message as Sendable),
+    recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
+    recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
+    recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
+    recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
+    getGuilds: () => bot.guildService.getList(),
+    getChannels: (guildId) => bot.channelService.getList(guildId),
+    getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
+    getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
+    getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
+    createGuildRole: (guildId, name, color) =>
+      bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
+    addMemberRole: async (guildId, channelId, userId, roleId) => {
+      await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
+      return true;
+    },
+    removeMemberRole: async (guildId, channelId, userId, roleId) => {
+      await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
+      return true;
+    },
+    approveGroupJoinRequest: (groupId, userId, options) =>
+      (bot as { approveGroupJoinRequest?: QqBotTransport['approveGroupJoinRequest'] })
+        .approveGroupJoinRequest?.(groupId, userId, options)
+      ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+    middleware: (ctx, next) => bot.middleware(ctx as never, next as never),
+  };
+}

package/src/ws.ts

@@ -0,0 +1,331 @@
+/**
+ * QQ WebSocket transport: bot factory and inbound message normalization.
+ */
+import path from 'node:path';
+import {
+  Bot,
+  ReceiverMode,
+  type ApproveJoinRequestOptions,
+  type Sendable,
+} from 'qq-official-bot';
+import type { MediaRef, Segment } from '@zhin.js/im-contract';
+import type { QqOutboundMessage } from './outbound.js';
+import type { QqChannelKind, QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
+
+/** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
+export type QqOfficialApi = Pick<Bot,
+  | 'messageService'
+  | 'fileProcessor'
+  | 'guildService'
+  | 'channelService'
+  | 'memberService'
+  | 'permissionService'
+  | 'reactionService'
+  | 'scheduleService'
+  | 'threadService'
+  | 'audioService'
+  | 'botService'
+  | 'groupService'
+  | 'menuPanelService'
+  | 'group'
+  | 'user'
+  | 'channel'
+  | 'direct'
+  | 'guild'
+>;
+
+/** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
+export interface QqBotTransport {
+  /** Full qq-official-bot business API; lifecycle remains owned by the Endpoint. */
+  readonly api: QqOfficialApi;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  removeAllListeners(): void;
+  sendPrivateMessage(userId: string, message: QqOutboundMessage): Promise<unknown>;
+  sendGroupMessage(groupId: string, message: QqOutboundMessage): Promise<unknown>;
+  sendGuildMessage(channelId: string, message: QqOutboundMessage): Promise<unknown>;
+  sendDirectMessage?(guildId: string, message: QqOutboundMessage): Promise<unknown>;
+  recallPrivateMessage?(userId: string, messageId: string): Promise<unknown>;
+  recallGroupMessage?(groupId: string, messageId: string): Promise<unknown>;
+  recallGuildMessage?(channelId: string, messageId: string): Promise<unknown>;
+  recallDirectMessage?(guildId: string, messageId: string): Promise<unknown>;
+  getGuilds(): Promise<unknown[]>;
+  getChannels(guildId: string): Promise<unknown[]>;
+  getChannelInfo(channelId: string): Promise<unknown>;
+  getGuildMember(guildId: string, userId: string): Promise<unknown>;
+  getGuildRoles(guildId: string): Promise<unknown[]>;
+  createGuildRole(guildId: string, name: string, color?: number): Promise<unknown>;
+  addMemberRole(
+    guildId: string,
+    channelId: string,
+    userId: string,
+    roleId: string,
+  ): Promise<boolean>;
+  removeMemberRole(
+    guildId: string,
+    channelId: string,
+    userId: string,
+    roleId: string,
+  ): Promise<boolean>;
+  approveGroupJoinRequest?(
+    groupId: string,
+    userId: string,
+    options: ApproveJoinRequestOptions,
+  ): Promise<unknown>;
+}
+
+export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+
+interface QqOfficialBotLifecycle {
+  stop(): Promise<unknown>;
+  readonly sessionManager: {
+    userClose: boolean;
+    readonly connectionManager?: { destroy(): void };
+    readonly authManager?: { destroy(): void };
+  };
+}
+
+/**
+ * qq-official-bot 1.2 used a separate connection manager; 1.3 moved WebSocket
+ * ownership into the receiver, but Session.stop() still leaves the auth refresh
+ * manager alive. Mark the session closed, clean up legacy connections when
+ * present, stop the receiver, then destroy auth refresh at the SDK boundary.
+ */
+export async function stopQqOfficialBot(bot: QqOfficialBotLifecycle): Promise<void> {
+  const session = bot.sessionManager;
+  session.userClose = true;
+  session.connectionManager?.destroy();
+  try {
+    await bot.stop();
+  } finally {
+    session.authManager?.destroy();
+  }
+}
+
+export function bindQqBotInboundEvents(
+  bot: QqBotTransport,
+  admitRaw: (raw: unknown) => void,
+): void {
+  bot.on('message.group', admitRaw);
+  bot.on('message.guild', admitRaw);
+  bot.on('message.private', admitRaw);
+}
+
+export function normalizeQqMessage(raw: unknown): QqInboundMessage | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const msg = raw as {
+    message_id?: string | number;
+    message_type?: string;
+    sub_type?: string;
+    user_id?: string | number;
+    group_id?: string | number;
+    group_openid?: string;
+    channel_id?: string | number;
+    guild_id?: string | number;
+    raw_message?: string;
+    message?: unknown;
+    sender?: { user_id?: string | number; user_name?: string; roles?: (string | number)[] };
+    member?: { roles?: (string | number)[] };
+    author?: { member_openid?: string; user_openid?: string; id?: string; username?: string };
+    /** AT 事件载荷：被 @ 的用户列表；is_you 标识当前机器人，bot 标识机器人账号 */
+    mentions?: Array<{ id?: string | number; bot?: boolean; is_you?: boolean; member_openid?: string; member_role?: string }>;
+  };
+  if (msg.message_id == null) return null;
+
+  let channelKind: QqChannelKind = 'private';
+  let channelId = '';
+
+  const isGroup = msg.message_type === 'group'
+    || (msg.message_type == null && (msg.group_id != null || msg.group_openid != null));
+  const isGuild = msg.message_type === 'guild'
+    || (msg.message_type == null && !isGroup && msg.guild_id != null && msg.channel_id != null);
+
+  if (isGuild) {
+    channelKind = msg.sub_type === 'direct' ? 'direct' : 'channel';
+    channelId = channelKind === 'direct'
+      ? String(msg.guild_id ?? '')
+      : String(msg.channel_id ?? '');
+  } else if (isGroup) {
+    channelKind = 'group';
+    channelId = String(msg.group_id ?? msg.group_openid ?? '');
+  } else {
+    channelKind = 'private';
+    channelId = String(msg.user_id ?? msg.author?.user_openid ?? msg.author?.id ?? '');
+  }
+  if (!channelId) return null;
+
+  const authorId = String(
+    msg.sender?.user_id
+    ?? msg.user_id
+    ?? msg.author?.member_openid
+    ?? msg.author?.user_openid
+    ?? msg.author?.id
+    ?? '',
+  );
+  const content = extractTextContent(msg.message) || msg.raw_message || '';
+  const segments = extractCanonicalSegments(msg.message);
+  const rawRoles = msg.member?.roles ?? msg.sender?.roles;
+  const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
+  // 统一按 mentions 判定 @：is_you 精确标识当前机器人（群载荷实测字段）。
+  // 群里 @ 另一个机器人时 mentions 带 bot:true 但无 is_you，不能误判为 @ 当前机器人，
+  // 故群场景只认 is_you；bot 回退仅限频道 AT_MESSAGE_CREATE（该事件仅 @ 当前
+  // 机器人时下发，其 mentions 无 is_you）。
+  const mentioned = Array.isArray(msg.mentions)
+    && msg.mentions.some((m) => m?.is_you === true || (m?.bot === true && channelKind !== 'group'));
+
+  return {
+    id: String(msg.message_id),
+    content,
+    channelKind,
+    channelId,
+    authorId,
+    authorName: msg.sender?.user_name || msg.author?.username || authorId,
+    authorRoles,
+    timestamp: Date.now(),
+    guildId: msg.guild_id != null ? String(msg.guild_id) : undefined,
+    rawMessage: msg.raw_message,
+    ...(segments.length > 0 ? { segments } : {}),
+    ...(mentioned ? { mentioned: true } : {}),
+  };
+}
+
+/**
+ * SDK 解析后的消息段（text/at/face/image/video/audio/file/reply）→ canonical Segment[]。
+ * 附件段的 url 已由 SDK 归一（补 https:// 前缀）；mime 无法从载荷得知时按类型给默认。
+ */
+function extractCanonicalSegments(message: unknown): Segment[] {
+  if (!Array.isArray(message)) return [];
+  const out: Segment[] = [];
+  for (const seg of message) {
+    if (!seg || typeof seg !== 'object') continue;
+    const item = seg as { type?: string; data?: Record<string, unknown> };
+    const type = item.type ?? '';
+    const data = item.data ?? {};
+    switch (type) {
+      case 'text': {
+        const text = String(data.text ?? '');
+        if (text) out.push({ type: 'text', data: { text } });
+        break;
+      }
+      case 'at': {
+        const target = String(data.user_id ?? data.id ?? '');
+        if (!target) break;
+        const name = typeof data.username === 'string' && data.username
+          ? data.username
+          : undefined;
+        out.push({ type: 'mention', data: name ? { target, name } : { target } });
+        break;
+      }
+      case 'face': {
+        const id = data.id;
+        if (id == null) break;
+        out.push({ type: 'face', data: { id: id as string | number } });
+        break;
+      }
+      case 'image':
+      case 'video':
+      case 'audio':
+      case 'file': {
+        const url = typeof data.url === 'string' ? data.url : '';
+        if (!url) break;
+        const media: MediaRef = {
+          kind: 'url',
+          value: url,
+          mime_type: defaultMimeForSegment(type),
+          ...(typeof data.name === 'string' && data.name ? { file_name: data.name } : {}),
+          ...(typeof data.size === 'number' ? { size: data.size } : {}),
+        };
+        if (type === 'image') out.push({ type: 'image', data: { media } });
+        else if (type === 'video') out.push({ type: 'video', data: { media } });
+        else if (type === 'audio') out.push({ type: 'audio', data: { media } });
+        else out.push({ type: 'file', data: { media, ...(media.file_name ? { name: media.file_name } : {}) } });
+        break;
+      }
+      case 'reply': {
+        const messageId = String(data.id ?? data.message_id ?? '');
+        if (messageId) out.push({ type: 'reply', data: { message_id: messageId } });
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return out;
+}
+
+function defaultMimeForSegment(type: string): string | undefined {
+  switch (type) {
+    case 'image': return 'image/jpeg';
+    case 'video': return 'video/mp4';
+    case 'audio': return 'audio/mpeg';
+    default: return undefined;
+  }
+}
+
+function extractTextContent(message: unknown): string {
+  if (typeof message === 'string') return message;
+  if (!Array.isArray(message)) return '';
+  return message
+    .map((seg) => {
+      if (!seg || typeof seg !== 'object') return '';
+      const item = seg as { type?: string; data?: { text?: string }; text?: string };
+      if (item.type === 'text') return String(item.data?.text ?? item.text ?? '');
+      return '';
+    })
+    .join('');
+}
+
+export function defaultCreateBot(config: ResolvedQqWebsocketConfig): QqBotTransport {
+  const bot = new Bot({
+    appid: config.appid,
+    secret: config.secret,
+    mode: ReceiverMode.WEBSOCKET,
+    sandbox: config.sandbox,
+    dataDir: path.join(process.cwd(), 'data', 'qq'),
+    // 关闭 qq-official-bot 内置 log4js，入/出站由 getAdapterLogger('qq', …) 统一格式
+    logLevel: 'off',
+    ...(config.intents ? { intents: config.intents as never } : {}),
+    ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
+    ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
+  });
+
+  return {
+    api: bot,
+    start: () => bot.start().then(() => undefined),
+    stop: () => stopQqOfficialBot(bot as unknown as QqOfficialBotLifecycle),
+    on: (event, listener) => {
+      bot.on(event as never, listener as never);
+    },
+    removeAllListeners: () => {
+      bot.removeAllListeners(undefined as never);
+    },
+    sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message as Sendable),
+    sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message as Sendable),
+    sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message as Sendable),
+    sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message as Sendable),
+    recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
+    recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
+    recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),
+    recallDirectMessage: (guildId, messageId) => bot.recallDirectMessage(guildId, messageId),
+    getGuilds: () => bot.guildService.getList(),
+    getChannels: (guildId) => bot.channelService.getList(guildId),
+    getChannelInfo: (channelId) => bot.channelService.getInfo(channelId),
+    getGuildMember: (guildId, userId) => bot.memberService.getGuildMemberInfo(guildId, userId),
+    getGuildRoles: (guildId) => bot.guildService.getRoles(guildId),
+    createGuildRole: (guildId, name, color) =>
+      bot.guildService.createRole(guildId, { name, color: color || 0, hoist: 0 }),
+    addMemberRole: async (guildId, channelId, userId, roleId) => {
+      await bot.memberService.addMemberRole(guildId, channelId, userId, roleId);
+      return true;
+    },
+    removeMemberRole: async (guildId, channelId, userId, roleId) => {
+      await bot.memberService.removeMemberRole(guildId, channelId, userId, roleId);
+      return true;
+    },
+    approveGroupJoinRequest: (groupId, userId, options) =>
+      (bot as { approveGroupJoinRequest?: QqBotTransport['approveGroupJoinRequest'] })
+        .approveGroupJoinRequest?.(groupId, userId, options)
+      ?? Promise.reject(new Error('approveGroupJoinRequest is not available')),
+  };
+}