@zhin.js/adapter-qq 1.0.83 → 1.1.0

package/src/qq-endpoint-commands.ts

@@ -0,0 +1,251 @@
+/**
+ * `qq.endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/endpoint/ 下的命令文件默认导出。
+ */
+import {
+  createEndpointCommands,
+  endpointCommandForbidden,
+  extractEndpointCommandReply,
+  formatEndpointList,
+  isEndpointOperator,
+  removeEndpointById,
+  type ConfiguredEndpointEntry,
+  type EndpointCommandReply,
+} from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from './qq-bot-kind-prompt.js';
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+import { addQqEndpointToConfig, listQqEndpointEntries } from './qq-endpoint-config.js';
+import { defaultQqEndpointIntentFields, type QqBotKind } from './qq-intents.js';
+import {
+  qqRuntimeStateToken,
+  type QqPendingBotKind,
+  type QqRuntimeState,
+} from './qq-runtime-state.js';
+
+export type QqCommandReply = EndpointCommandReply;
+
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export function isQqEndpointOperator(config: unknown, input: unknown): boolean {
+  return isEndpointOperator(config, input);
+}
+
+export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
+
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractQqCommandReply(input: unknown): QqCommandReply {
+  return extractEndpointCommandReply(input);
+}
+
+function busyFooter(state: QqRuntimeState): string | undefined {
+  if (state.bindFlow) return '⚠️ 有进行中的扫码绑定，可用 qq.endpoint cancel 取消';
+  if (state.pendingBotKind) {
+    return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq.endpoint cancel`;
+  }
+  return undefined;
+}
+
+/** `qq.endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string {
+  return formatEndpointList(qqEndpointListSpec, {
+    running: state.endpoints.values(),
+    configured: listQqEndpointEntries(projectRoot),
+    footer: busyFooter(state),
+  });
+}
+
+const qqEndpointListSpec = {
+  adapterKey: 'qq',
+  adapterDisplayName: 'QQ',
+  describeEntry: (entry: ConfiguredEndpointEntry) => `appid: ${String(entry.appid)}`,
+} as const;
+
+function writeEndpointWithBotKind(
+  pending: QqPendingBotKind,
+  botKind: QqBotKind,
+  projectRoot?: string,
+): string {
+  const envKeys = persistQqCredentialsToEnv(
+    pending.endpointId,
+    pending.appId,
+    pending.appSecret,
+    projectRoot,
+  );
+  const intentFields = defaultQqEndpointIntentFields(botKind);
+  const filePath = addQqEndpointToConfig(
+    {
+      id: pending.endpointId,
+      appid: envKeys.appidRef,
+      secret: envKeys.secretRef,
+      botKind: intentFields.botKind,
+      intents: [...intentFields.intents],
+    },
+    projectRoot,
+  );
+  return (
+    `✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
+    `intents: ${intentFields.intents.join(', ')}。\n` +
+    '⚠️ 需重启 zhin 后新 endpoint 才会生效。'
+  );
+}
+
+/**
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export function completeQqPendingBotKind(
+  pending: QqPendingBotKind,
+  botKind: QqBotKind,
+  projectRoot?: string,
+): string {
+  return writeEndpointWithBotKind(pending, botKind, projectRoot);
+}
+
+/**
+ * `qq.endpoint add [id]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
+ */
+export function runQqEndpointAdd(
+  state: QqRuntimeState,
+  id: string | undefined,
+  reply: QqCommandReply,
+  projectRoot?: string,
+  input?: unknown,
+): Promise<string> {
+  if (state.bindFlow || state.pendingBotKind) {
+    return Promise.resolve(
+      '已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq.endpoint cancel 取消后再试',
+    );
+  }
+  const endpointId = id?.trim() || undefined;
+  const sessionKey = qqCommandSessionKey(input);
+  return new Promise<string>((resolve) => {
+    let firstReplied = false;
+    const settle = (text: string) => {
+      if (!firstReplied) {
+        firstReplied = true;
+        resolve(text);
+        return;
+      }
+      // Follow-ups outlive the inbound Message reply scope; durable reply
+      // (OutboundHost) is provided by createEndpointCommands.bindFlow. Never
+      // let a late notify crash the process.
+      void Promise.resolve(reply(text)).catch(() => undefined);
+    };
+    const stop = startQqBindFlow(
+      {
+        onQrDisplayed: (url) => {
+          // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
+          settle(
+            `请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`,
+          );
+        },
+        onQrExpired: async () => {
+          try {
+            await reply('二维码已过期，正在刷新，请扫描新链接…');
+          } catch {
+            // same as settle follow-up: best-effort after command scope ends
+          }
+        },
+        onSuccess: async (credentials) => {
+          state.bindFlow = null;
+          try {
+            const [{ appId, appSecret }] = credentials;
+            const finalName = endpointId ?? appId;
+
+            // 无会话上下文（Host 等）时无法追问，直接按公域一次性写入
+            if (!sessionKey) {
+              settle(
+                writeEndpointWithBotKind(
+                  {
+                    endpointId: finalName,
+                    appId,
+                    appSecret,
+                    sessionKey: '',
+                  },
+                  'public',
+                  projectRoot,
+                ) +
+                '\n（当前会话无法交互选择公/私域；私域请手动改配置。）',
+              );
+              return;
+            }
+
+            state.pendingBotKind = {
+              endpointId: finalName,
+              appId,
+              appSecret,
+              sessionKey,
+            };
+            settle(
+              `✅ 扫码成功！endpoint「${finalName}」。\n` +
+              QQ_BOT_KIND_PROMPT,
+            );
+          } catch (error) {
+            settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+          }
+        },
+        onFailure: (error) => {
+          state.bindFlow = null;
+          settle(`❌ QQ 绑定失败：${error.message}`);
+        },
+      },
+      { source: 'zhin' },
+    );
+    state.bindFlow = { id: endpointId, stop };
+  });
+}
+
+/** `qq.endpoint cancel`：中止进行中的绑定或待选 botKind */
+export function runQqEndpointCancel(state: QqRuntimeState): string {
+  if (state.bindFlow) {
+    state.bindFlow.stop();
+    state.bindFlow = null;
+    return '已取消进行中的 QQ 绑定流程';
+  }
+  if (state.pendingBotKind) {
+    const name = state.pendingBotKind.endpointId;
+    state.pendingBotKind = null;
+    return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
+  }
+  return '当前没有进行中的 QQ 绑定流程';
+}
+
+/** `qq.endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export function runQqEndpointRemove(
+  _state: QqRuntimeState,
+  id: string,
+  projectRoot?: string,
+): string {
+  return removeEndpointById(qqEndpointListSpec, id, projectRoot);
+}
+
+/**
+ * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
+ */
+export const qqEndpointCommands = createEndpointCommands({
+  ...qqEndpointListSpec,
+  fields: [
+    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
+    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+  ],
+  running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+  listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+  addDescription:
+    '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
+  bindFlow: ({ id, reply, input, use }) =>
+    runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, undefined, input),
+}, defineCommand);

package/src/qq-endpoint-config.ts

@@ -0,0 +1,44 @@
+/**
+ * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
+ * 实现已泛化到 @zhin.js/adapter 的 endpoint-commands 套件（Document 节点级保留注释）；
+ * 本文件仅保留 QQ 专用签名以兼容既有调用与测试。
+ */
+import {
+  addEndpointToConfig,
+  findEndpointConfigFile,
+  listConfiguredEndpoints,
+  removeEndpointFromConfig,
+} from 'zhin.js/adapter';
+
+export interface QqEndpointConfigEntry {
+  id: string;
+  appid: string;
+  secret: string;
+  [key: string]: unknown;
+}
+
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findQqConfigFile(projectRoot?: string): string {
+  return findEndpointConfigFile('qq', projectRoot);
+}
+
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[] {
+  return listConfiguredEndpoints('qq', projectRoot) as QqEndpointConfigEntry[];
+}
+
+/** 追加 endpoint 到 plugins.qq.endpoints；id 已存在时报错 */
+export function addQqEndpointToConfig(
+  entry: QqEndpointConfigEntry,
+  projectRoot?: string,
+): string {
+  return addEndpointToConfig('qq', entry, projectRoot);
+}
+
+/** 按 id 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(
+  id: string,
+  projectRoot?: string,
+): { removed: boolean; filePath: string } {
+  return removeEndpointFromConfig('qq', id, projectRoot);
+}

package/src/qq-intents.ts

@@ -0,0 +1,77 @@
+/**
+ * QQ 官方机器人 intents 与公域/私域映射。
+ *
+ * 群聊无公/私域之分，两类都订阅 `GROUP_AND_C2C_EVENT`。
+ * 频道消息 intent 不同：
+ * - public（公域）：`PUBLIC_GUILD_MESSAGES`（仅 @ 机器人）
+ * - private（私域）：`GUILD_MESSAGES`（频道全量消息；公域订阅会 Identify 失败）
+ */
+
+export type QqBotKind = 'public' | 'private';
+
+export type QqIntent =
+  | 'GUILDS'
+  | 'GUILD_MEMBERS'
+  | 'GUILD_MESSAGES'
+  | 'GUILD_MESSAGE_REACTIONS'
+  | 'DIRECT_MESSAGE'
+  | 'GROUP_AND_C2C_EVENT'
+  | 'INTERACTION'
+  | 'MESSAGE_AUDIT'
+  | 'FORUMS_EVENT'
+  | 'AUDIO_ACTION'
+  | 'PUBLIC_GUILD_MESSAGES'
+  | 'GROUP_MEMBER';
+
+/** 扫码绑定 / 未声明 botKind 时的默认（公域更常见）。 */
+export const DEFAULT_QQ_BOT_KIND: QqBotKind = 'public';
+
+/** 公/私域共用：群/C2C、群成员变更、频道基础事件、频道私信。 */
+const QQ_SHARED_INTENTS = Object.freeze([
+  'GROUP_AND_C2C_EVENT',
+  'GROUP_MEMBER',
+  'GUILDS',
+  'GUILD_MEMBERS',
+  'DIRECT_MESSAGE',
+] as const satisfies readonly QqIntent[]);
+
+export const QQ_INTENTS_BY_KIND: Readonly<Record<QqBotKind, readonly QqIntent[]>> = Object.freeze({
+  public: Object.freeze([
+    ...QQ_SHARED_INTENTS,
+    'PUBLIC_GUILD_MESSAGES',
+  ] as const),
+  private: Object.freeze([
+    ...QQ_SHARED_INTENTS,
+    'GUILD_MESSAGES',
+  ] as const),
+});
+
+/** 解析 botKind：仅接受 `public` / `private`。 */
+export function parseQqBotKind(value: unknown): QqBotKind | undefined {
+  if (value === 'public' || value === 'private') return value;
+  return undefined;
+}
+
+/**
+ * 解析最终 intents：显式 `intents` 优先；否则按 `botKind`（默认 public）展开。
+ */
+export function resolveQqIntents(input: {
+  readonly intents?: readonly string[] | undefined;
+  readonly botKind?: unknown;
+}): readonly QqIntent[] {
+  if (Array.isArray(input.intents) && input.intents.length > 0) {
+    return Object.freeze(input.intents.map(String)) as readonly QqIntent[];
+  }
+  const kind = parseQqBotKind(input.botKind) ?? DEFAULT_QQ_BOT_KIND;
+  return QQ_INTENTS_BY_KIND[kind];
+}
+
+/** 添加 endpoint 时写入配置的默认字段（显式展开，便于用户改）。 */
+export function defaultQqEndpointIntentFields(
+  botKind: QqBotKind = DEFAULT_QQ_BOT_KIND,
+): { readonly botKind: QqBotKind; readonly intents: readonly QqIntent[] } {
+  return Object.freeze({
+    botKind,
+    intents: QQ_INTENTS_BY_KIND[botKind],
+  });
+}

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),
+  };
+}