@zhin.js/adapter-qq 5.0.1 → 5.0.3

package/src/index.ts

@@ -1,371 +1,58 @@
-/**
- * QQ 官方适配器入口：类型扩展、导出、注册
- */
-import path from "node:path";
-import { usePlugin, type Plugin, type ISceneManagement, createSceneManagementTools, type ToolFeature } from "zhin.js";
-import type { Router } from "@zhin.js/host-router";
-import { QQAdapter } from "./adapter.js";
-import { PageManager } from "@zhin.js/host-api";
-import {
+export {
+  formatInboundContent,
+  formatInboundTarget,
+  formatOutboundText,
+  parseSendTarget,
+  resolveOutboundMessageId,
+  resolveQqConfig,
+  senderDisplayName,
+  type ParsedSendTarget,
+  type QqAdapterConfig,
+  type QqChannelKind,
+  type QqInboundMessage,
+  type QqWireSegment,
+  type ResolvedQqConfig,
+  type ResolvedQqHttpConfig,
+  type ResolvedQqWebsocketConfig,
+} from './protocol.js';
+
+export {
+  QqHttpEndpoint,
+  QqWebsocketEndpoint,
+  type CreateQqBot,
+  type CreateQqHttpBot,
+  type QqBotTransport,
+  type QqEndpointOptions,
+  type QqHttpBotTransport,
+  type QqHttpEndpointOptions,
+} from './endpoint.js';
+
+export {
+  registerQqWebhookRoutes,
+  handleQqWebhookRequest,
+  readRequestBodyText,
+  defaultCreateHttpBot,
+  type QqWebhookHandler,
+} from './webhook.js';
+
+export {
+  bindQqBotInboundEvents,
+  defaultCreateBot,
+  normalizeQqMessage,
+} from './ws.js';
+
+export {
+  getQqAgentDeps,
+  registerQqAgentEndpoint,
+  setQqAgentDeps,
+  type QqAgentDeps,
+  type QqAgentEndpoint,
+} from './qq-agent-deps.js';
+
+export {
+  checkQqPlatformPermit,
+  normalizeQqGuildSenderForPermit,
   platformPermit,
   qqGuildPermitResolver,
   registerQqPlatformPermitChecker,
-} from "./platform-permit.js";
-import { disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-
-declare module "zhin.js" {
-  namespace Plugin {
-    interface Contexts {
-      web: PageManager;
-      router: Router;
-    }
-  }
-}
-
-declare module "zhin.js" {
-  interface Adapters {
-    qq: QQAdapter;
-  }
-}
-
-export * from "./types.js";
-export { QQEndpoint } from "./endpoint.js";
-export { QQAdapter } from "./adapter.js";
-export { startQqBindFlow } from "./qq-bind-flow.js";
-export * from "./qq-bind-api.js";
-export { QqEndpointManager, disposeQqEndpointProvision } from "./qq-endpoint-manager.js";
-
-const plugin = usePlugin();
-const { provide, useContext, onDispose } = plugin;
-
-useContext("router", (router: Router) => {
-  provide({
-    name: "qq",
-    description: "QQ Official Endpoint Adapter",
-    mounted: async (p: Plugin) => {
-      const adapter = new QQAdapter(p, router);
-      await adapter.start();
-      return adapter;
-    },
-    dispose: async (adapter: QQAdapter) => {
-      await adapter.stop();
-    },
-  });
-});
-
-useContext('tool', 'qq', (toolService: ToolFeature, qq: QQAdapter) => {
-  const disposers: (() => void)[] = [];
-  disposers.push(registerQqPlatformPermitChecker());
-  const sceneTools = createSceneManagementTools(
-    qq as unknown as ISceneManagement,
-    'qq',
-    { permitResolver: qqGuildPermitResolver, registerChecker: false },
-  );
-  disposers.push(...sceneTools.map(t => toolService.addTool(t, plugin.name)));
-
-  // 获取频道列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_guilds',
-    description: '获取 QQ 频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-      },
-      required: ['endpoint_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const guilds = await endpoint.getGuilds();
-      return { guilds, count: guilds.length };
-    },
-  }, plugin.name));
-
-  // 获取子频道列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_channels',
-    description: '获取 QQ 频道下的子频道列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['endpoint_id', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_channels')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const channels = await endpoint.getChannels(args.guild_id);
-      return { channels, count: channels.length };
-    },
-  }, plugin.name));
-
-  // 获取角色列表
-  disposers.push(toolService.addTool({
-    name: 'qq_list_roles',
-    description: '获取 QQ 频道角色列表',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-      },
-      required: ['endpoint_id', 'guild_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const roles = await endpoint.getGuildRoles(args.guild_id);
-      return { roles, count: roles.length };
-    },
-  }, plugin.name));
-
-  // 创建角色
-  disposers.push(toolService.addTool({
-    name: 'qq_create_role',
-    description: '创建 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        name: { type: 'string', description: '角色名称' },
-        color: { type: 'number', description: '颜色（RGB 十进制数值）' },
-      },
-      required: ['endpoint_id', 'guild_id', 'name'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_owner')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const role = await endpoint.createGuildRole(args.guild_id, args.name, args.color);
-      return { success: !!role, role, message: role ? `角色 "${args.name}" 创建成功` : '创建失败' };
-    },
-  }, plugin.name));
-
-  // 添加角色
-  disposers.push(toolService.addTool({
-    name: 'qq_add_role',
-    description: '给成员添加 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.addMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已给成员添加角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 移除角色
-  disposers.push(toolService.addTool({
-    name: 'qq_remove_role',
-    description: '移除成员的 QQ 频道角色',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-        role_id: { type: 'string', description: '角色 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'channel_id', 'user_id', 'role_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('manage_roles')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const success = await endpoint.removeMemberRole(args.guild_id, args.channel_id, args.user_id, args.role_id);
-      return { success, message: success ? '已移除成员的角色' : '操作失败' };
-    },
-  }, plugin.name));
-
-  // 子频道详情
-  disposers.push(toolService.addTool({
-    name: 'qq_channel_info',
-    description: '获取 QQ 频道中指定子频道的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        channel_id: { type: 'string', description: '子频道 ID' },
-      },
-      required: ['endpoint_id', 'channel_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_admin')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const info = await endpoint.getChannelInfo(args.channel_id);
-      return info;
-    },
-  }, plugin.name));
-
-  // 单成员详情
-  disposers.push(toolService.addTool({
-    name: 'qq_member_detail',
-    description: '获取 QQ 频道中指定成员的详细信息',
-    parameters: {
-      type: 'object',
-      properties: {
-        endpoint_id: { type: 'string', description: 'Endpoint 名称', contextKey: 'endpointId' },
-        guild_id: { type: 'string', description: '频道 ID' },
-        user_id: { type: 'string', description: '用户 ID' },
-      },
-      required: ['endpoint_id', 'guild_id', 'user_id'],
-    },
-    platforms: ['qq'],
-    tags: ['qq'],
-    permissions: [platformPermit('guild_admin')],
-    execute: async (args: Record<string, any>) => {
-      const endpoint = qq.endpoints.get(args.endpoint_id);
-      if (!endpoint) throw new Error(`Endpoint ${args.endpoint_id} 不存在`);
-      const member = await endpoint.getGuildMember(args.guild_id, args.user_id);
-      return member;
-    },
-  }, plugin.name));
-
-  return () => disposers.forEach(d => d());
-});
-
-// ── Web 控制台 ─────────────────────────────────────────────────────────
-useContext("web", (pageManager) => {
-  pageManager.addEntry({
-    id: "qq",
-    development: path.resolve(import.meta.dirname, "../client/index.tsx"),
-    production: path.resolve(import.meta.dirname, "../dist/index.js"),
-    meta: { name: "QQ" },
-  });
-});
-
-useContext("router", "qq", (router: any, qq: QQAdapter) => {
-  router.get("/api/qq/endpoints", async (ctx: any) => {
-    try {
-      const endpoints = Array.from(qq.endpoints.values());
-      const result = await Promise.all(endpoints.map(async (endpoint) => {
-        try {
-          let guildCount = 0;
-          try { const guilds = await endpoint.getGuilds(); guildCount = guilds?.length || 0; } catch {}
-          return {
-            name: endpoint.$config.name,
-            connected: endpoint.$connected || false,
-            guildCount,
-            status: endpoint.$connected ? "online" : "offline",
-          };
-        } catch {
-          return { name: endpoint.$config.name, connected: false, guildCount: 0, status: "error" };
-        }
-      }));
-      ctx.body = { success: true, data: result };
-    } catch {
-      ctx.status = 500;
-      ctx.body = { success: false, error: "获取 Endpoint 数据失败" };
-    }
-  });
-
-  // Endpoint 连接/断开
-  router.post("/api/qq/endpoints/:name/connect", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (endpoint.$connected) { ctx.body = { success: true, message: "已经在线" }; return; }
-      await endpoint.$connect();
-      ctx.body = { success: true, message: "连接成功" };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "连接失败" };
-    }
-  });
-
-  router.post("/api/qq/endpoints/:name/disconnect", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.body = { success: true, message: "已经离线" }; return; }
-      await endpoint.$disconnect();
-      ctx.body = { success: true, message: "已断开" };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "断开失败" };
-    }
-  });
-
-  // 频道列表（QQ 官方 API 返回 guild_id/guild_name，归一化为控制台用的 id/name）
-  router.get("/api/qq/endpoints/:name/guilds", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Endpoint 未连接" }; return; }
-      const raw = await endpoint.getGuilds();
-      const guilds = (raw || []).map((g: any) => ({
-        id: g.guild_id ?? g.id,
-        name: g.guild_name ?? g.name,
-        icon: g.icon,
-        description: g.description,
-        memberCount: g.member_count,
-        ownerId: g.owner_id,
-        owner: g.owner,
-        joinTime: g.join_time,
-      }));
-      ctx.body = { success: true, data: guilds };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "获取频道失败" };
-    }
-  });
-
-  // 子频道列表（QQ 官方 API 返回 channel_id/channel_name，归一化为 id/name）
-  router.get("/api/qq/endpoints/:name/guilds/:guildId/channels", async (ctx: any) => {
-    try {
-      const endpoint = qq.endpoints.get(ctx.params.name);
-      if (!endpoint) { ctx.status = 404; ctx.body = { success: false, error: "Endpoint 不存在" }; return; }
-      if (!endpoint.$connected) { ctx.status = 400; ctx.body = { success: false, error: "Endpoint 未连接" }; return; }
-      const raw = await endpoint.getChannels(ctx.params.guildId);
-      const channels = (raw || []).map((ch: any) => ({
-        id: ch.channel_id ?? ch.id,
-        name: ch.channel_name ?? ch.name,
-        type: ch.type,
-        subType: ch.sub_type,
-        position: ch.position,
-        parentId: ch.parent_id,
-      }));
-      ctx.body = { success: true, data: channels };
-    } catch (e: unknown) {
-      ctx.status = 500;
-      ctx.body = { success: false, error: e instanceof Error ? e.message : "获取子频道失败" };
-    }
-  });
-});
-
-onDispose(() => {
-  disposeQqEndpointProvision();
-});
+} from './platform-permit.js';

package/src/platform-permit.ts

@@ -1,8 +1,7 @@
 /**
  * QQ 官方频道 platform permit（guild/channel，非 QQ 群 group_*）
  */
-import type { Message } from 'zhin.js';
-import { registerPlatformPermitChecker } from 'zhin.js';
+import { registerPlatformPermitChecker, type Message } from '@zhin.js/core';
 
 const ADAPTER = 'qq';
 

package/src/protocol.ts

@@ -0,0 +1,229 @@
+/**
+ * QQ Official Bot protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+
+import { pickCredential } from '@zhin.js/adapter';
+
+/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
+export interface QqAdapterConfig {
+  readonly name?: string;
+  readonly appid?: string;
+  readonly secret?: string;
+  /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
+  readonly mode?: 'websocket' | 'webhook' | 'middleware';
+  readonly sandbox?: boolean;
+  readonly intents?: readonly string[];
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+  readonly webhookPath?: string;
+  readonly port?: number;
+  readonly path?: string;
+  /** Transitional: legacy root `endpoints[]` with `context: qq`. */
+  readonly endpoints?: ReadonlyArray<{
+    readonly context?: string;
+    readonly name?: string;
+    readonly appid?: string;
+    readonly secret?: string;
+    readonly mode?: 'websocket' | 'webhook' | 'middleware';
+    readonly sandbox?: boolean;
+    readonly intents?: readonly string[];
+    readonly accessTokenUrl?: string;
+    readonly gatewayUrl?: string;
+    readonly webhookPath?: string;
+    readonly port?: number;
+    readonly path?: string;
+  }>;
+}
+
+export interface ResolvedQqWebsocketConfig {
+  readonly context: 'qq';
+  readonly mode: 'websocket';
+  readonly name: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly sandbox: boolean;
+  readonly intents?: readonly string[];
+  readonly accessTokenUrl?: string;
+  readonly gatewayUrl?: string;
+}
+
+export interface ResolvedQqHttpConfig {
+  readonly context: 'qq';
+  readonly mode: 'webhook' | 'middleware';
+  readonly name: string;
+  readonly appid: string;
+  readonly secret: string;
+  readonly webhookPath: string;
+  readonly sandbox: boolean;
+}
+
+export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;
+
+export type QqChannelKind = 'private' | 'group' | 'channel' | 'direct';
+
+export interface QqInboundMessage {
+  readonly id: string;
+  readonly content: string;
+  readonly channelKind: QqChannelKind;
+  readonly channelId: string;
+  readonly authorId: string;
+  readonly authorName: string;
+  readonly authorRoles?: string[];
+  readonly timestamp: number;
+  readonly guildId?: string;
+  readonly rawMessage?: string;
+  /**
+   * 入站即 @ 机器人（AT_MESSAGE_CREATE 的 mentions[].bot，或群 GROUP_AT_MESSAGE_CREATE
+   * 事件本身仅 @ 时下发）。新 Runtime 纯文本 content 需经 metadata 传递。
+   */
+  readonly mentioned?: boolean;
+}
+
+export interface QqWireSegment {
+  readonly type: string;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface ParsedSendTarget {
+  readonly kind: QqChannelKind;
+  readonly id: string;
+}
+
+export function resolveQqConfig(config: QqAdapterConfig = {}): ResolvedQqConfig {
+  const entry = config.endpoints?.find((item) => item.context === 'qq' || !item.context);
+  const appid = pickCredential(config.appid, entry?.appid, process.env.QQ_APPID, process.env.QQ_BOT_APPID);
+  const secret = pickCredential(config.secret, entry?.secret, process.env.QQ_SECRET, process.env.QQ_BOT_SECRET);
+  if (!appid || !secret) {
+    throw new TypeError(
+      'QQ adapter requires appid + secret (plugins.<key>.appid/secret or endpoints with context: qq)',
+    );
+  }
+  const name = (typeof config.name === 'string' && config.name)
+    || (typeof entry?.name === 'string' && entry.name)
+    || process.env.QQ_BOT_NAME
+    || 'qq-bot';
+  const mode = config.mode ?? entry?.mode ?? 'websocket';
+
+  if (mode === 'webhook' || mode === 'middleware') {
+    const webhookPathRaw = config.webhookPath ?? entry?.webhookPath ?? '/qq/webhook';
+    const webhookPath = webhookPathRaw.startsWith('/') ? webhookPathRaw : `/${webhookPathRaw}`;
+    return {
+      context: 'qq',
+      mode,
+      name,
+      appid,
+      secret,
+      webhookPath,
+      sandbox: config.sandbox === true || entry?.sandbox === true,
+    };
+  }
+
+  return {
+    context: 'qq',
+    mode: 'websocket',
+    name,
+    appid,
+    secret,
+    sandbox: config.sandbox === true || entry?.sandbox === true,
+    intents: config.intents ?? entry?.intents,
+    accessTokenUrl: config.accessTokenUrl ?? entry?.accessTokenUrl,
+    gatewayUrl: config.gatewayUrl ?? entry?.gatewayUrl,
+  };
+}
+
+/**
+ * Gateway reply target：`private:uid` / `group:gid` / `channel:cid` / `direct:guildId`.
+ */
+export function formatInboundTarget(msg: QqInboundMessage): string {
+  return `${msg.channelKind}:${msg.channelId}`;
+}
+
+export function parseSendTarget(target: string): ParsedSendTarget {
+  const sep = target.indexOf(':');
+  if (sep <= 0) {
+    return { kind: 'private', id: target };
+  }
+  const head = target.slice(0, sep);
+  const rest = target.slice(sep + 1);
+  if (head === 'private' || head === 'group' || head === 'channel' || head === 'direct') {
+    return { kind: head, id: rest };
+  }
+  return { kind: 'private', id: target };
+}
+
+export function senderDisplayName(msg: QqInboundMessage): string {
+  return msg.authorName || msg.authorId;
+}
+
+export function formatInboundContent(msg: QqInboundMessage): string {
+  const text = (msg.content || msg.rawMessage || '').trim();
+  return text || '(Empty message)';
+}
+
+/**
+ * Wire-encode an already-rendered outbound payload into a plain text / QQ Sendable string.
+ * Segment canonicalization is intentionally not done here.
+ */
+export function formatOutboundText(payload: unknown): string {
+  if (typeof payload === 'string') return payload;
+
+  const segments: Array<string | QqWireSegment> = Array.isArray(payload)
+    ? payload as Array<string | QqWireSegment>
+    : payload && typeof payload === 'object' && 'type' in (payload as object)
+      ? [payload as QqWireSegment]
+      : [];
+
+  if (segments.length === 0) {
+    return payload == null
+      ? ''
+      : typeof payload === 'object'
+        ? JSON.stringify(payload)
+        : String(payload);
+  }
+
+  return segments
+    .map((item) => {
+      if (typeof item === 'string') return item;
+      const data = item.data ?? {};
+      switch (item.type) {
+        case 'text':
+          return String(data.text ?? data.content ?? '');
+        case 'at': {
+          const id = String(data.user_id ?? data.qq ?? data.id ?? '');
+          return id ? `<@!${id}>` : '';
+        }
+        case 'image':
+          return String(data.url || data.file || '');
+        case 'reply':
+          return '';
+        default:
+          return data.text != null ? String(data.text) : '';
+      }
+    })
+    .filter(Boolean)
+    .join('');
+}
+
+/** 从 QQ API SendResult / 审核回包中解析出站消息 ID */
+export function resolveOutboundMessageId(result: unknown): string {
+  if (!result || typeof result !== 'object') {
+    throw new Error('QQ 发送消息失败：响应为空');
+  }
+  const row = result as Record<string, unknown>;
+  const nested = row.data && typeof row.data === 'object'
+    ? row.data as Record<string, unknown>
+    : undefined;
+  const audit = (row.message_audit ?? nested?.message_audit) as Record<string, unknown> | undefined;
+  const id = row.id ?? row.message_id ?? audit?.audit_id;
+  if (id == null || id === '') {
+    const code = row.code;
+    const msg = row.message;
+    throw new Error(
+      code != null
+        ? `QQ 发送消息失败（${String(code)}）${msg ? `: ${String(msg)}` : ''}`
+        : 'QQ 发送消息失败：响应缺少消息 ID',
+    );
+  }
+  return String(id);
+}