@zhin.js/adapter-qq 5.0.2 → 6.0.0

package/src/qq-endpoint-commands.ts

@@ -0,0 +1,174 @@
+/**
+ * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ */
+import { startQqBindFlow } from './qq-bind-flow.js';
+import { persistQqCredentialsToEnv } from './qq-bind-persist.js';
+import {
+  addQqEndpointToConfig,
+  listQqEndpointEntries,
+  removeQqEndpointFromConfig,
+} from './qq-endpoint-config.js';
+import type { QqRuntimeState } from './qq-runtime-state.js';
+
+export type QqCommandReply = (text: string) => Promise<unknown>;
+
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export function isQqEndpointOperator(config: unknown, input: unknown): boolean {
+  const cfg = (config ?? {}) as { master?: unknown; endpoints?: unknown };
+  const masters = new Set<string>();
+  const collect = (value: unknown) => {
+    if (value === undefined || value === null) return;
+    const text = String(value).trim();
+    if (text) masters.add(text);
+  };
+  collect(cfg.master);
+  if (Array.isArray(cfg.endpoints)) {
+    for (const entry of cfg.endpoints) {
+      collect((entry as { master?: unknown } | null | undefined)?.master);
+    }
+  }
+  if (masters.size === 0) return true;
+  const sender = String((input as { sender?: unknown } | null | undefined)?.sender ?? '').trim();
+  return !!sender && masters.has(sender);
+}
+
+export const QQ_ENDPOINT_FORBIDDEN = '仅 master 可执行 QQ endpoint 管理命令';
+
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractQqCommandReply(input: unknown): QqCommandReply {
+  const reply = (input as { $reply?: unknown } | null | undefined)?.$reply;
+  if (typeof reply === 'function') {
+    return (text) => (reply as (content: string) => Promise<unknown>).call(input, text);
+  }
+  return async () => undefined;
+}
+
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export function runQqEndpointList(state: QqRuntimeState, projectRoot?: string): string {
+  const running = [...state.endpoints.values()];
+  const configured = listQqEndpointEntries(projectRoot);
+  const lines: string[] = [];
+  lines.push('【运行中的 QQ endpoints】');
+  if (running.length === 0) {
+    lines.push('  （无）');
+  } else {
+    for (const endpoint of running) {
+      lines.push(`  - ${endpoint.name}（${endpoint.mode}）`);
+    }
+  }
+  lines.push('【配置中的 QQ endpoints】（zhin.config.yml → plugins.qq.endpoints）');
+  if (configured.length === 0) {
+    lines.push('  （无）');
+  } else {
+    for (const entry of configured) {
+      lines.push(`  - ${entry.name}（appid: ${entry.appid}）`);
+    }
+  }
+  if (state.bindFlow) {
+    lines.push('⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * `qq endpoint add [name]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ */
+export function runQqEndpointAdd(
+  state: QqRuntimeState,
+  name: string | undefined,
+  reply: QqCommandReply,
+  projectRoot?: string,
+): Promise<string> {
+  if (state.bindFlow) {
+    return Promise.resolve('已有进行中的 QQ 机器人绑定，请先发送 qq endpoint cancel 取消后再试');
+  }
+  const endpointName = name?.trim() || undefined;
+  return new Promise<string>((resolve) => {
+    let firstReplied = false;
+    const settle = (text: string) => {
+      if (!firstReplied) {
+        firstReplied = true;
+        resolve(text);
+        return;
+      }
+      void reply(text);
+    };
+    const stop = startQqBindFlow(
+      {
+        onQrDisplayed: (url) => {
+          // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
+          settle(
+            `请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`,
+          );
+        },
+        onQrExpired: async () => {
+          await reply('二维码已过期，正在刷新，请扫描新链接…');
+        },
+        onSuccess: async (credentials) => {
+          state.bindFlow = null;
+          try {
+            const [{ appId, appSecret }] = credentials;
+            const finalName = endpointName ?? appId;
+            const envKeys = persistQqCredentialsToEnv(finalName, appId, appSecret, projectRoot);
+            const filePath = addQqEndpointToConfig(
+              { name: finalName, appid: envKeys.appidRef, secret: envKeys.secretRef },
+              projectRoot,
+            );
+            settle(
+              `✅ 绑定成功！endpoint「${finalName}」的凭据已写入 .env，并已追加到 ${filePath} 的 plugins.qq.endpoints。\n` +
+              '⚠️ 需重启 zhin 后新 endpoint 才会生效。',
+            );
+          } catch (error) {
+            settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+          }
+        },
+        onFailure: (error) => {
+          state.bindFlow = null;
+          settle(`❌ QQ 绑定失败：${error.message}`);
+        },
+      },
+      { source: 'zhin' },
+    );
+    state.bindFlow = { name: endpointName, stop };
+  });
+}
+
+/** `qq endpoint cancel`：中止进行中的绑定流程 */
+export function runQqEndpointCancel(state: QqRuntimeState): string {
+  if (!state.bindFlow) {
+    return '当前没有进行中的 QQ 绑定流程';
+  }
+  state.bindFlow.stop();
+  state.bindFlow = null;
+  return '已取消进行中的 QQ 绑定流程';
+}
+
+/** `qq endpoint remove <name>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export function runQqEndpointRemove(
+  _state: QqRuntimeState,
+  name: string,
+  projectRoot?: string,
+): string {
+  const trimmed = name.trim();
+  if (!trimmed) return '用法：qq endpoint remove <name>';
+  try {
+    const { removed, filePath } = removeQqEndpointFromConfig(trimmed, projectRoot);
+    if (!removed) {
+      return `配置中不存在 qq endpoint「${trimmed}」（${filePath} → plugins.qq.endpoints）`;
+    }
+    return (
+      `已从 ${filePath} 的 plugins.qq.endpoints 移除「${trimmed}」。\n` +
+      '⚠️ 需重启 zhin 后生效（运行中的连接届时才会断开）；.env 中的凭据键未删除，可手动清理。'
+    );
+  } catch (error) {
+    return `移除失败：${error instanceof Error ? error.message : String(error)}`;
+  }
+}

package/src/qq-endpoint-config.ts

@@ -0,0 +1,135 @@
+/**
+ * zhin.config.yml 中 plugins.qq.endpoints 的读写（Plugin Runtime 版）。
+ * 用 yaml Document 操作以保留现有注释；仅支持 .yml/.yaml，其它格式报错提示手动处理。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isMap, isSeq, parseDocument, type YAMLSeq } from 'yaml';
+import { resolveProjectRoot } from './qq-bind-persist.js';
+
+export interface QqEndpointConfigEntry {
+  name: string;
+  appid: string;
+  secret: string;
+  [key: string]: unknown;
+}
+
+const CONFIG_BASENAME = 'zhin.config';
+const YAML_EXTENSIONS = ['.yml', '.yaml'] as const;
+
+/** 定位项目配置文件：ZHIN_CONFIG 指定优先，否则发现 zhin.config.yml/.yaml，都没有则默认新建 zhin.config.yml */
+export function findQqConfigFile(projectRoot?: string): string {
+  const root = projectRoot ?? resolveProjectRoot();
+  const envConfig = process.env.ZHIN_CONFIG?.trim();
+  if (envConfig) return path.resolve(root, envConfig);
+  for (const ext of YAML_EXTENSIONS) {
+    const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  for (const ext of ['.json', '.toml', '.ts'] as const) {
+    const candidate = path.join(root, `${CONFIG_BASENAME}${ext}`);
+    if (fs.existsSync(candidate)) {
+      throw new Error(`暂不支持写入 ${ext} 配置文件，请手动在 ${CONFIG_BASENAME}${ext} 的 plugins.qq.endpoints 中维护`);
+    }
+  }
+  return path.join(root, `${CONFIG_BASENAME}.yml`);
+}
+
+interface QqConfigDocument {
+  filePath: string;
+  doc: ReturnType<typeof parseDocument>;
+}
+
+function readConfigDocument(projectRoot?: string): QqConfigDocument {
+  const filePath = findQqConfigFile(projectRoot);
+  const content = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf-8') : '';
+  const doc = parseDocument(content || '{}');
+  return { filePath, doc };
+}
+
+function writeConfigDocument({ filePath, doc }: QqConfigDocument): void {
+  fs.writeFileSync(filePath, doc.toString());
+}
+
+/** 读取 plugins.qq.endpoints（plain JS）；plugins/qq 缺失或形态不符时返回 [] */
+export function listQqEndpointEntries(projectRoot?: string): QqEndpointConfigEntry[] {
+  const { doc } = readConfigDocument(projectRoot);
+  const plugins = doc.toJS()?.plugins;
+  if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins)) return [];
+  const endpoints = (plugins as { qq?: { endpoints?: unknown } }).qq?.endpoints;
+  if (!Array.isArray(endpoints)) return [];
+  return endpoints.filter(
+    (entry): entry is QqEndpointConfigEntry =>
+      !!entry && typeof entry === 'object' && typeof (entry as { name?: unknown }).name === 'string',
+  );
+}
+
+function entryName(item: unknown): string | undefined {
+  if (!isMap(item)) return undefined;
+  const name = item.get('name');
+  return typeof name === 'string' && name ? name : undefined;
+}
+
+/**
+ * 确保 plugins.qq.endpoints 存在并返回其 YAMLSeq（节点级操作，保留既有条目与注释）。
+ * `plugins: []`（legacy 空列表，Runtime 忽略）可直接替换为 map；非空数组拒绝写入。
+ */
+function ensureEndpointsSeq(doc: ReturnType<typeof parseDocument>): YAMLSeq {
+  const plugins = doc.get('plugins');
+  if (isSeq(plugins) && plugins.items.length > 0) {
+    throw new Error('配置的 plugins 是数组形态（legacy 插件名列表），请手动迁移为 map 后再试');
+  }
+  if (plugins !== undefined && !isMap(plugins) && !isSeq(plugins)) {
+    throw new Error('配置的 plugins 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isMap(doc.get('plugins'))) {
+    // 注意：空对象 {} 不会被 doc.set 自动包装为 YAMLMap，必须显式 createNode
+    doc.set('plugins', doc.createNode({}));
+  }
+  const qq = doc.getIn(['plugins', 'qq']);
+  if (qq !== undefined && !isMap(qq)) {
+    throw new Error('配置的 plugins.qq 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isMap(doc.getIn(['plugins', 'qq']))) {
+    doc.setIn(['plugins', 'qq'], doc.createNode({}));
+  }
+  const endpoints = doc.getIn(['plugins', 'qq', 'endpoints']);
+  if (endpoints !== undefined && !isSeq(endpoints)) {
+    throw new Error('配置的 plugins.qq.endpoints 字段形态异常，请手动检查 zhin.config.yml');
+  }
+  if (!isSeq(doc.getIn(['plugins', 'qq', 'endpoints']))) {
+    doc.setIn(['plugins', 'qq', 'endpoints'], doc.createNode([]));
+  }
+  return doc.getIn(['plugins', 'qq', 'endpoints']) as YAMLSeq;
+}
+
+/** 追加 endpoint 到 plugins.qq.endpoints；name 已存在时报错 */
+export function addQqEndpointToConfig(
+  entry: QqEndpointConfigEntry,
+  projectRoot?: string,
+): string {
+  const document = readConfigDocument(projectRoot);
+  const seq = ensureEndpointsSeq(document.doc);
+  if (seq.items.some((item) => entryName(item) === entry.name)) {
+    throw new Error(`配置中已存在 qq endpoint「${entry.name}」，可先 qq endpoint remove ${entry.name} 再重新添加`);
+  }
+  seq.items.push(document.doc.createNode(entry));
+  writeConfigDocument(document);
+  return document.filePath;
+}
+
+/** 按 name 移除 plugins.qq.endpoints 项；不存在返回 false */
+export function removeQqEndpointFromConfig(
+  name: string,
+  projectRoot?: string,
+): { removed: boolean; filePath: string } {
+  const document = readConfigDocument(projectRoot);
+  const seq = ensureEndpointsSeq(document.doc);
+  const next = seq.items.filter((item) => entryName(item) !== name);
+  if (next.length === seq.items.length) {
+    return { removed: false, filePath: document.filePath };
+  }
+  seq.items = next;
+  writeConfigDocument(document);
+  return { removed: true, filePath: document.filePath };
+}

package/src/qq-runtime-state.ts

@@ -0,0 +1,36 @@
+/**
+ * QQ 插件实例的运行时状态：adapter create() 注册的 endpoint 列表 +
+ * 扫码绑定流程的全局单例。由 plugin.ts setup() provide，
+ * adapter create 与 commands 通过 use(qqRuntimeStateToken) 共享（同一 owner generation）。
+ */
+import { createToken } from '@zhin.js/plugin-runtime';
+
+export interface QqRunningEndpoint {
+  name: string;
+  mode: string;
+}
+
+export interface QqBindFlowHandle {
+  /** 绑定期望的 endpoint 名（未指定时为 undefined，成功后取 appId） */
+  name?: string;
+  stop: () => void;
+}
+
+export interface QqRuntimeState {
+  /** 当前 generation 已成功创建的 endpoint（name → 描述） */
+  readonly endpoints: Map<string, QqRunningEndpoint>;
+  /** 全局单例：同一时间只允许一个扫码绑定流程 */
+  bindFlow: QqBindFlowHandle | null;
+}
+
+export function createQqRuntimeState(): QqRuntimeState {
+  return {
+    endpoints: new Map(),
+    bindFlow: null,
+  };
+}
+
+export const qqRuntimeStateToken = createToken<QqRuntimeState>(
+  'zhin.qq.runtime-state',
+  'QQ adapter runtime state (running endpoints + bind flow singleton)',
+);

package/src/webhook.ts

@@ -0,0 +1,127 @@
+/**
+ * QQ HTTP webhook / middleware inbound via httpHostToken POST.
+ */
+import path from 'node:path';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { Bot, ReceiverMode } 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 {
+    let parsedBody: unknown;
+    const raw = await readRequestBodyText(request);
+    if (raw) {
+      try {
+        parsedBody = JSON.parse(raw);
+      } catch {
+        parsedBody = undefined;
+      }
+    }
+    await bot.middleware({
+      req: request,
+      res: response,
+      request: { body: parsedBody },
+    }, 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'),
+  } as never) as Bot<ReceiverMode.MIDDLEWARE, 'koa'> & QqBotTransport;
+
+  return {
+    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),
+    sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
+    sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
+    sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+    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;
+    },
+    middleware: (ctx, next) => bot.middleware(ctx as never, next as never),
+  };
+}

package/src/ws.ts

@@ -0,0 +1,172 @@
+/**
+ * QQ WebSocket transport: bot factory and inbound message normalization.
+ */
+import path from 'node:path';
+import { Bot, ReceiverMode } from 'qq-official-bot';
+import { getLevel, toLog4jsLevel } from '@zhin.js/logger';
+import type { QqChannelKind, QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
+
+/** Minimal bot surface used by the endpoint (real qq-official-bot or test mock). */
+export interface QqBotTransport {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  on(event: string, listener: (...args: unknown[]) => void): void;
+  removeAllListeners(): void;
+  sendPrivateMessage(userId: string, message: string): Promise<unknown>;
+  sendGroupMessage(groupId: string, message: string): Promise<unknown>;
+  sendGuildMessage(channelId: string, message: string): Promise<unknown>;
+  sendDirectMessage?(guildId: string, message: 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>;
+}
+
+export type CreateQqBot = (config: ResolvedQqWebsocketConfig) => QqBotTransport;
+
+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_MESSAGE_CREATE 载荷：被 @ 的用户列表，bot=true 即机器人 */
+    mentions?: Array<{ id?: string | number; bot?: boolean }>;
+  };
+  if (msg.message_id == null) return null;
+
+  let channelKind: QqChannelKind = 'private';
+  let channelId = '';
+  if (msg.message_type === 'guild') {
+    channelKind = msg.sub_type === 'direct' ? 'direct' : 'channel';
+    channelId = channelKind === 'direct'
+      ? String(msg.guild_id ?? '')
+      : String(msg.channel_id ?? '');
+  } else if (msg.message_type === 'group') {
+    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 rawRoles = msg.member?.roles ?? msg.sender?.roles;
+  const authorRoles = Array.isArray(rawRoles) ? rawRoles.map(String) : undefined;
+  // 群 GROUP_AT_MESSAGE_CREATE 仅 @ 机器人时下发；频道 AT 事件看 mentions[].bot
+  const mentioned = channelKind === 'group'
+    || (Array.isArray(msg.mentions) && msg.mentions.some((m) => m?.bot === true));
+
+  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,
+    ...(mentioned ? { mentioned: true } : {}),
+  };
+}
+
+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'),
+    logLevel: toLog4jsLevel(getLevel()),
+    ...(config.intents ? { intents: config.intents as never } : {}),
+    ...(config.accessTokenUrl ? { accessTokenUrl: config.accessTokenUrl } : {}),
+    ...(config.gatewayUrl ? { gatewayUrl: config.gatewayUrl } : {}),
+  });
+
+  return {
+    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),
+    sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
+    sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
+    sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+    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;
+    },
+  };
+}